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Crescent Division of Progress Software 
14 Oak Park, Bedford, MA 01730 USA 


NEW! ClassAction™ 

API function calls can be hard to access, learn and use. Now, 
ClassAction makes exploiting the Windows API a breeze. 
ClassAction, a collection of Windows objects implemented as 

a VB4 classes, makes complex system calls as simple as property 
changes or method calls. With ClassAction, you'll get more struc- 
tured, readable, and maintainable code, and build more powerful 
applications in a fraction of the time. 


NEW! EnQuiry™ 

At last! A point-and-click SQL query building tool for VB. 
EnQuiry leads you step-by-step through the query building process. 
See query table relationships at a glance. The Query Advisor™ 
ensures proper SQL syntax. Other features include automatic control 
placement, multiple layout styles, and a form preview. Now you can 
develop database applications in a fraction of the time. List $299 


XRef™ 


Get control of your code. View, analyze, and manage your 
application-in-progress. Generate lists of key program parameters, 
call-tree reports, and source code listings. View properties and events 
of your custom controls and data objects. With XRef you'll avoid 
hours of tedious backtracking and investigation. List $129 


at 800-352-2742 From outside the us 


at crescent@progress.com 


at 617-280-4025 
Visit our World Wide Web site at 


Windows and Visual Basic are registered trademarks of Microsoft Corporation. Crescent, XRef, EnQuiry ,Crescent Internet ToolPak, 
of Crescent Division of Progress Software Corporation. All other trademarks referenced are property of their respective owners. 
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NEW! VB4 Plus Pak™ 

A fun way to leap the VB4 learning curve. In VB4 Plus Pak you get 
our valuable VB4 Transition Guide, and Upgrade Wizard, plus the 
Client/Server White Paper. It also includes these useful utilities: 
Class Wizard, Stock Quote Monitor, SMTP Send Mail Control, 
PDQComm Weather Wizard, and the Smile Bound Control - a 
model OLE control with source code. A must-have for the novice 
and expert alike. 


Crescent Internet ToolP. 

Your window to the world of the Internet for VB4. Build Internet-enabled 
applications without low-level coding or in-depth knowledge 

of Internet protocols. There’s a mail wizard that walks you through your 
Internet application, building the groundwork for your mail project. Con- 
trols include Internet Mail (SMTP and POP), USENET Newsgroups, 
Web/http, FTP, & client/server, and they all conform to applicable RFC 
standards. Internet ToolPak works in event-driven mode and the numer- 
ous demo programs and sample code make it easy to learn and use. 
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QuickPak® Professional 

Get a head start delivering high-performance VB4 applications 

with this arsenal of over 29 custom controls, more than 250 DLL 
routines, and dozens of sample programs. You get a 3D calendar 
display with drag and drop support, Hypertext tools, data aware con- 
trols, combo boxes and more. QuickPak Professional lets you do 
things in VB you never could before. List $249 


Proven Reusable 
Components 


GRESCENT 


Division of Progress Software 


http: //www.progress.com/crescent 


ClassAction and VB4 PlusPak are trademarks of Crescent Division of Progress Software Corporation. QuickPak, is a registered trademarks 
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Enhanced keyboard support 


any OLE control froma cell 


per column, even per cell 
Automatic translation of 
database field values for 
display (e.g., display 0, 7 
as “Unpaid” and “Paid”) 


In-cell graphics, combo box, 
check box and radio buttons 


Multiple rows/columns 

selection ¢ Complete on-line help 
and plenty of examples 

Display format mask 


Free runtime distribution 
Full international 
characters support 


And much more! 


For the long term stability and compatibility 
of your company's mission critical applications 


True DBGrid is the enhanced, full-featured version of DBGrid that ships with Microsoft Visual Basic 4.0. When you use 
True DBGrid you know you will automatically satisfy all (current and future) software standards set by Microsoft, and you 
will be the first to benefit from the latest OLE and database technologies to be built-in all Microsoft development systems. 
If long term stability and compatibility is your number one concern, then True DBGrid is the only data grid of choice! 


Add analytical power to pour applications with VSFlex 


You mean It's free?! 


While True DBGrid by APEX provides you with the latest data For a limited time only, you can get 


binding and data presentation technologies, VSFlex by Videosoft VSFlex/OCX (16 and 32-bit OCX, MSRP . 
adds analytical power to your applications. Just add data to the $149) absolutely free* when you purchase w 
FlexArray control, set a couple of properties, and Viola! Your True DBGrid. You get data binding, data pres- ie 


users can dynamically pivot the data between columns. All the 
data is automatically sorted, merged and re-arranged. 


MSRP in USA: 


19 


DBGrid 


entation, and data analysis power in one package at 
an incredibly low price. Order now before offer expires! 


APEX Software Corporation 
4516 Henry Street 
Pittsburgh, PA 15213 
Phone (412) 681-4343 

Toll Free 800-858-2739 
Fax (412) 681-4384 


/\P=X 


True DBGrid and the True DBGrid logo are trademarks of APEX Software Corporation. Visual Basic is a 
trademark of Microsoft Corporation. Other product names are the properties of their respective owners. 


Web: http://www.apexsc.com/ 
CompuServe: GO APEX 
Internet: sales@apexsc.com 


All APEX products come with a 30-day, no-hassle, money-back guarantee. 
Our free technical support service is among the very best in the industry. 


* VSFlex/OCX comes with complete on-line help and documentation. 
Manual for VSFlex/OCX is not included in this special offer. 


Free VOFIOS 


Call 1-800-858-2739 for the retail store or local reseller nearest you! 
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Keith Pleas shows you how to be 


2 a raider of the Win32 registry. 
Jungle courtesy of Indoor Design Plant 
Service, Palo Alto, California. 


To download the sample code for the 
articles in this issue, visit the Magazine 
Library of the VBPJ Forum on 
CompuServe (GO WINDX with 
WinCIM); the VBPJ Development 
Exchange World Wide Web site (http: 
//www.windx.com); or the VBPJ site on 
The Microsoft Network (GO WINDX). 
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22 || HACKING THE WINDOWS REGISTRY oy Keith Pleas 


You don’t need a bullwhip or a machete to hack through the Windows registration 
database. A copy of RegEdit will do, along with the author’s expert guidance. 


44 KEEP IN SYNC WITH JET REPLICATION by Pout Litwin 


Jet 3.0's database synchronization and replication support increases your data-sharing 
options, and eases the daunting task of implementing these crucial features. 


54 A WALKING TOUR OF RDO ty wittiam R. Vaughn 


A pioneering developer suffers the slings and arrows of implementing a client/server 
system using RDO. It turns out he made the right choice for his system’s size and design. 


62, THUNK BEFORE YOU PORT by steve Jackson 


We thunk, therefore we allow our 32-bit applications to call 16-bit third-party DLLs. We 
save time and money. We are smart. 


68, READING THE MAIL by Peter Vogel 


MAPI gives you the benefits of workflow automation features such as built-in fault 
tolerance and administration capabilities—for free! Don’t tell Microsoft. 
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by Andrew J. Brust by Chris Barlow | 
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by Richard Hale Shaw by Karl E. Peterson 
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by L.J. Johnson by Carl Franklin 


OLE Expert does not appear in this issue. See Roger Jennings’ Interactive Developer 
column for OLE-oriented discourse. OLE Expert returns next month. 
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NOW DESIGNING 


DATABASE FRONT ENDS IS SO 
EASY IT’S EMBARRASSING. 


Introducing Data Widgets 2.0 


Data Widgets 2 


Dramatically increase the produc- 
tivity of your Microsoft® Visual 
Basic" 4.0 application development 
with Data Widgets 2.0 from 
Sheridan Software. Data Widgets 
2.0 is a set of bound OLE controls 
that lets you design front ends 
for database applications in the 
shortest amount of time with all 
the ease and power you’ve come 
to expect from Visual Basic. 


Data Widgets 2.0 is designed to 
optimize your Visual Basic 4.0 
database front ends, supplied as 
16- and 32-bit OLE Controls. 
Included area fully editable 
DataGrid, a DataCombo (the 
dropdown and edit portions can 
be bound to different databases), 
Enhanced Data Controls, a 
DataDropDown, a Data Command 
and a DataOptionSet Control. 


(Visual Basic 
Programmer's 


Thunderbolt { 


S| Miciosoh Press 
IMictosoft Press Div of: Microsoft Corp. 


1One Microsoft We 
edmond 


Drop-in 


Replacement for Visual 


Basic 4.0’s grid. 


DataGrid™(SSDBGrid) 
Functionally and visually consistent with data grids 
in Microsoft Access and Visual Basic 4.0. 
Support for movable groups and columns. 
Optional dropdowns in headings allow users to select 
from a list of available fields and/or groups at run time. 
© Additional cell types include checkbox, button, 
label, and combo box. 
° Multiline row formats. 
Pictures and text in cells and headings. 
Individual fonts and colors for columns, rows, and cells. 
© Full design time capabilities. 
Supports multiple data modes including bound, 
unbound, and AddItem (design and run time). 


Data Combo (SSDBCombo] 
Variable edit area height a la Microsoft Access. 
© Multiline edit area. 
>» DropDown display is not limited to the width 
of the edit area. 
Same formatting capabilities as the SSDBGrid control. 
Full design time capabilities. 


DataDropDown (SSDBDropDown) 
© Used in conjunction with the DataGrid. 
DropDown display is not limited to the width of 
the edit area. 
Same formatting capabilities as the SSDBGrid control. 
Full design time capabilities. 


Manufacturer’s List Price: 


$ 139.00 


Data Option Set (SSDBOpiSet) 
One control creates an unlimited number of 
option buttons that are bound to the same 
data field. 
» Multi line captions and pictures. 
Automatic and manual button positioning. 

e Custom color options. 


Enhanced Data Control (SSDBDaia) 
Re-position recordset by selecting from a 
drop down list of up to 100 previously 
marked rows. 

Store and sort multiple bookmarks in the 
bookmark drop down list. 

Buttons that perform database actions such 
as add, delete, update, plus bi-directional 
nth record paging. 

Conditional and Soundex searching. 
ToolTips 


Data Command (SSDBCommand) 
» Multiline captions and pictures. 
© Add, Delete, Refresh, Bookmark, and 
Auto-Positioning functions. 
Click and AfterClick events. 
Auto-Repeat functionality. 
Custom color options. 


1-800-VB DIRECT 


Sheridan. 


Reusable Components and Productivity Tools 
for the Visual Developer 


Sheridan Software Systems 
35 Pinelawn Road, Melville, e New York 11747 


Voice: (516) 753-0985 © Fax: (516) 753-3661 © BBS: (516) 753-5452 
CIS: GO SHERIDAN e http://www. shersoft.com 


© 1993-1996 Sheridan Software Systems, Inc. All rights reserved. Data Widgets, DataGrid and the Sheridan logo are trademarks of Sheridan Software Systems, Inc. Microsoft, and Visual Basic are registered trademarks of Microsoft Corporation. 


Return of the 
Dreaded GoTo 


“There are no facts, there is no truth, just data to be manipulated.” 
— Don Henley, “In the Garden of Allah,” ASCAP. 


lhe biggest trend in computer programming isn’t object-oriented develop- 
| ment. In fact, the entire concept of structured development is about to be 

| thrown out, with the return of the GoTo as the hottest new concept in 
programming. Yes, you heard it here first, the GoTo is back and badder than ever. 

By now, you're thinking I’m crazy, but consider this sequence of events. We’re 
all being swept up by the Internet craze. Every product from Microsoft, with the 
possible exception of Solitaire, will become Net enabled. 

The hot new tool from Microsoft is VBScript. And the coalition of “everyone 
else against Microsoft” has anointed Java as its Lancelot to fight the Big Green 
Dragon from Bellevue. 

These tools are exciting. The ability to create download-and-run applications 
to enable client/server computing across the Internet will have a huge impact. 
The most visible examples will be public, commercial sites, but the biggest impact 
will be in design of internal sites—so-called “Intranet” applications. 

But, when you look at the code from any Web site, what do you see? Open any 
site’s content in your browser, choose the option to look at the HTML, and what’s 
there? A succession of GoTos. That’s all HTML is—a bunch of GoTos, and without 
even the help of line numbers. 

Web sites are huge agglomerations of spaghetti code. Try to map the structure 
of any site of significant size or content volume and you'll see what I mean. That’s 
why you get URL errors even on sites like Motorola’s or General Motors’— sites 
that cost half a million dollars to design. 

They've removed a section, and can’t find all the GoTos that called it. When 
software vendors ask my advice on setting up Web sites, I tell them their major 
expense will be maintenance because, basically, Web sites violate every design 
principal and, like any large software project, you pay the price during upkeep. 

Next, look at samples of VBScript code. It’s HTML mixed with subroutines. My 
first reaction was amazement at how powerful this will be. And it will. But, after 
four years of promoting VBA as a modern, structured language, denying its 
spaghetti-code heritage from GW BASIC days, VB is returning to its roots. This 
isn’t to say that Sun’s Java is any better. But the irony is worth enjoying. 

Java has earned amazing press coverage, and is credited for redefining the 
Web—an amazing achievement for a product that was in beta and hadn’t yet 
shipped. It’s promise is small, fast, portable appletts. To do this, Java is essen- 
tially a specialized version of C++ running atop an interpreter kernel. 

Wait a minute! Isn’t the primary criticism of VB its use of a pseudocode 
interpreter? So, the premise here is that if we combine the worst of both worlds— 
the difficulty of object-oriented programming with its long learning curve (re- 
member, most C++ owners actually still write C code) and the long development 
times of C++ with the poor performance of a p-code machine runtime DLL, then 
we'll have an exciting new tool. (Am I missing something?) 

That this concept, so highly touted in press from USA Todayto ComputerWorld, 
has problems is evident in Sun’s plans to create a Java compiler. In other words, 
when you log onto a site, it will have to determine what platform you're using and 
chose to download OCXs in Intel architecture, PowerPC architecture, SPARC— 
well, you get it. So, we’re back to choosing between portability and performance 
and the original premise gets tossed out the lowercase window. 

To deal with the relative unproductivity of C++, we'll be sold tools like 
Borland’s Latte, to put visual programming on top of C++, which itself runs on top 
of the p-code machine. 

All of this effort just to get back to where Visual Basic starts—while still being 
able to say you're programming in C++—so Unix-heads will love it. Seems obtuse 
to me. VBScript, however, with its higher level of abstraction and p-code inter- 
preter works as if it was designed for the Web. 

All this is the price of having the whole world networked, which probably 
makes it worthwhile. The Web’s impact is amazing. But let’s recognize that 
this isn’t all new, and it isn’t all good. From a software perspective, we’re 
reinventing the wheel and all the old problems are bound to resurface, to be 
solved once again. &l 
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Letters to Visual Basic Programmer’s Jour- 
nal are welcome. To be considered for 
publication, letters must include yourname, 
address, and daytime telephone number. 
Letters may be edited for form, fit, and 
style. Please send them to Letters to the 
Editor, c/o Fawcette Technical Publica- 
tions, 209 Hamilton Avenue, Palo Alto, CA 
94301-2500; fax them to 415-853-0230; or 
send them electronically on CompuServe 
to 74774,305 or on the Internet at 
74774.305@compuserve.com. 


CHAMPING AT THE 32 BITS 

Ward Hitt’s article “Tune for Blazing 
Speed” in the January issue of VBP/J was 
one of the most relevant and useful in the 
five-year history of the publication. I have 
ordered his book. 

Now, his treatment of the 16-bit/32-bit 
VB 4.0 issue is also top notch! Superior! 
One thing, though. It’s like saying, “Oh, 
and by the way, the world as we know it 
will end on March 7, 1996!” His numbers 
regarding speed, which I believe 100 per- 
cent because he did the legwork and actu- 
ally tested, fly in the face of everything 
we've been led to believe regarding VB 4.0 
and Windows 95 in general. 

The ads for VB 4.0 pretty much equate 
“Blazing Speed” with 32 bits! Now, to find 
that we’d have to be nuts to compile in 32 
bits (that’s certainly the way I take this— 
the things that are faster in 32 bits amount 
to nothing and I can do without the Rich 
Text control) is just plain shocking. We’re 
being lied to. His articleis the only hint of 
truth I’ve seen. 

Other people are getting hints of this. 
A few of us have noticed that VB 3.0 apps 
are running under Windows 95 faster 
than VB 4.0 apps (had one buddy say 
that his VB 4.0 app turned his Pentium 
into a 386!). That’s because we always 
compile in 32 bits. | mean, why shouldn’t 
we? Why are we running this neat 32-bit 
operating system anyway? 

Ihave two VB machines right now: one 
a 486/66 with eight megs of RAM (like the 
machine in the article) running Win 3.1 
and VB 3.0 and another, a P133 with 16 
megs of RAM running Win 95 and VB 4.0. 

I can tell you this. I’m gonna do every- 
thing on the old machine for now. To heck 
with VB 4.0! Who needs it? I’ve looked and 
looked. There’s no reason... none... forme 
to build stuff in 4.0 and have to include a 
run time that’s twice the size of VB 3.0’s. 
Where’s the “added value”? 

I think Ward Hitt’s article and discov- 
eries need more attention. Is he up to 
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being Microsoft Enemy Number One? Be- 
ing a VB professional, this must be quite 
the personal dilemma for him (would be 
for me). He’s done excellent work here. 
He’d be right to at least fear Microsoft to 
some measure. But he’d be more right to 
spread the word on this in some manner 
fitting its importance. 
Jeff Morris 
received by e-mail 


Thanks, Jeff, for your kind words about the 
article. I agree with you that VB4 32-bit 
performance is, to say the least, disap- 
pointing. And as you point out, the areas 
where 32-bit code is superior, such as 
mathematics, are not critical in some real- 
world optimization situations. 

I also agree that Microsoft blundered 
when they implemented an architecture 
that requires such huge distributables. With 
the world going on line, it’s essential that 
download times be kept to a reasonable 
level. [simply don’t buy the oft-heard argu- 
ment that we can distribute EXEs without 
the run times, assuming that our users will 
already have the latest DLLs installed. 
This only worked when all that was needed 
was VBRUN100.DLL. 

But don’t throw out the baby with the 
bath water. There are plenty of reasons to 
use VB4, most of which never made the 
top-10 feature lists. The new Printer object 
finally provides decent printing support. 
MDI children can now be hidden. Named 
and Optional parameters make creating 
reusable subroutines even easier. The ra- 
tional DAO model simplifies database pro- 
gramming. The new editor is far superior. 
And the list goes on. 

Of course, no feature excuses perfor- 
mance slowdowns in a development tool, 
and you can rest assured that VBPJ will 
stay on top of this issue, now and in the 
future. We’re currently preparing a follow- 
up to the performance article, which will 
compare VB3, VB4-16, and VB4-32 perfor- 
mance on Windows 3.1, 95, and NT using 
the same scientific approach used in my 
Optimizing Visual Basic 4 book and the 
January article. Look for it in the next 
couple of months.—W.H. 


A MATTER OF MAINTENANCE 
I think John Vaughn’s editorial is very 
thought provoking [“The True Cost of 
Code Maintenance,” Visual Basic 
Programmer’s Journal, December 1995]. 
If his assumptions are correct, the 
entire RAD concept is going to fail miser- 
ably because nobody can afford to pay 
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Waiting Ffor...? 
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No other product comes close to matching the value of VBTools” 5, the new version of MicroHelp’s award-winning VBTools product. 
VBTools 5 follows in the same tradition by providing developers the most diverse collection of solid, high quality components. 


VBTools 5 offers a multitude of controls for interface building, multimedia, 
fime management and much more! It is designed to work with any visual 


programming tool that supports type 1 VBXs. Plus, if you're 
using Visual Basic®, take advantage of the Microsoff® Access 
database engine by using any of the 23 data aware 
controls. 

The new version includes all the controls from VBTools 4 
with many feature enhancements. Significant functionality 
has been added to VBTools 5 with several new controls. 

Build sight and sound into your application with our new 
multimedia controls. The image control, with panning and 
zooming capabilities, can display many of the most popular 
image fi He | ormats, The WAV control enables you to store 
and playback WAV files, and the AVI control provides a 
simple interface for playing Windows® AVI files. 


MicroHel 
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VBTools is a trademark of MicroHelp Inc. Windows, 
Microsoft and Visual Bosic ore registered trademarks 
of Microsoft Corporation. 


Other new controls add essential Windows functionality to VBTools 5. The INI 
control does more than just edit Windows INI files, it lets you add, remove 
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Bring your productivity to new heights 
VBTools 5 - 
now with 60 VBX controls! 


p 


and modify entries in the Windows registry. The network 
control lets you integrate Windows supported networking into 
your applications, enabling you to add or remove netwo Mi 
connections and obtain user information. 

Order now to leverage the power of VBTools 5 and take your 
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that much for application program main- 
tenance. I think that a new paradigm is 
being invented in our industry, and we 
don’t even realize it. 

The new paradigm is: “Application 
programs are disposable.” Because the 
cost of development of an application 
program is, as he says, asmall fraction of 
the maintenance of it, the tendency will 
be to write a new application program 
instead of maintaining the existing one. 

This tendency is exaggerated by the 
“component model” of development, in 
which the major pieces of functionality 
are packaged as components which are 
purchased. In this case, the application 
program becomes a thin layer of GUI 
“glue” on top of the components. 

The components will usually not re- 
quire internal maintenance (if you buy 
them) once the application is fielded, so 
you only have to perform maintenance 
on the GUI glue part. If the application 
program is complicated or hard to main- 
tain, then it may be cheaper to pitch the 
old and make a new one, rather than try 
to maintain it. 

It is only feasible to discard a pro- 
gram that “works” in favor of develop- 
ment of a new one when the cost of 
development is much less than the cost 
of maintenance. Thus as we adopt 
cheaper development tools, it becomes 
more attractive to discard the old appli- 
cations instead of maintaining them. 

Also, because most of the “hard” code 
is now buried in purchased (or internally 
maintained) components, the maintenance 
of the thin-layer GUI application program 
becomes easier. This is especially true 
given that the “hellishly powerful program- 
ming environment” is also available to the 
maintenance programmers. 

Now this idea of disposable applica- 
tion programs is as yet unproven in prac- 
tice, so there is a lot of work in making 
the concept viable in production. I pre- 
sume your magazine will be generating 
articles in the future about “design for 
maintainability” and other methods of 
improving the maintenance process. 

We may be cursed, as in the Chinese 
proverb, to “live in interesting times”! 

John Alderman 
received on CompuServe 


I must take exception to the Guest Opin- 
ion by John Vaughn [“The True Cost of 
Code Maintenance,” Visual Basic 
Programmer’s Journal, December 1995]. 
Mr. Vaughn argues that the ratio of main- 
tenance time to development time for 
Visual Basic as compared to atraditional 
language will rise from about 4:1 (80-year 
maintenance to 20 years development in 
his example) to perhaps 49:1 (98 years 
maintenance to two years development 
in his example). Thus he argues that 


managers had better be very careful 
about the maintenance burden they are 
assuming in the brave new world of Vi- 
sual Basic. 

Fortunately his argument is specious. 
It is based on the assumption that main- 
tenance tools will operate at the effi- 
ciency of traditional languages while only 
development will be done using efficient 
modern tools such as Visual Basic. By 
analogy (and on a down-to-earth level) 
one would argue that while a giant 
earthen dam might be built using power 
equipment such as bulldozers and back- 
hoes, all maintenance must be done with 
hand shovels. Or ona programming level 
this dictates that a program written in C/ 
C++ can only be maintained at the ma- 
chine or assembly code level. 

Why doesn’t Mr. Vaughn believe main- 
tenance programmers will use the same 
tools as the developers? Sure there will 
be startup problems of maintaining ina 
new paradigm, but these problems will 
be solved with tools as powerful as those 
used for development. There may be 
many reasons to fear venturing forth 
into the brave new world, but program 
maintenance isn’t one of them. 

Jacob L. Raab 
Summit, New Jersey 


Read the last paragraph of Mr. Raab’s 
letter. In its first two sentences he encapsu- 
lates his argument and lays bare its flaws. 

“Why,” he asks, “doesn’t Mr. Vaughn 
believe [VB] maintenance programmers 
will use the same tools as the developers?” 
In fact I believe it entirely possible that 
they will do just that. But if they do they will 
be ill served. Development and mainte- 
nance are distinct activities. The tool that 
works well in one arena may fail utterly in 
the other. 

Consider the primitive COBOL genera- 
tors that enjoyed a brief vogue in the early 
1970s. For their time they were truly ca- 
pable development tools, but the code 
they produced was virtually impossible to 
read. Here we had a development tool not 
merely worthless in the maintenance pro- 
cess, but actively deleterious to it. 

In the next sentence Mr. Raab, perhaps 
sensing he is on shaky ground, abandons 
his assertion that VB maintenance pro- 
grammers will use the same tools as devel- 
opers. Instead they will use “[maintenance] 
tools as powerful as those used for devel- 
opment.” Note the use of the future tense. 
These tools do not yet exist, but Mr. Raab 
displays a touching faith that the clever 
people who now write VB development 
tools will be able to produce them when 
the need arises. This assumes that success 
in one endeavor is a sure predictor of 
another, acommon fallacy. In the 50s the 
world was certain that the scientists who 
had produced the first fission reactors 
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would have no trouble harnessing fusion. 
Forty years and many billions of dollars 
later, the world is still waiting. When Mr. 
Raab rests his argument on similar logic, 
he rests it on air. 

Mr. Raab’s reasoning is easily refuted. 
Nonetheless his letter is troubling, because 
people will read it and believe. They will 
believe because they like Visual Basic and 
do not want to hear that there may be a 
serpent in the garden. 

In a discipline as volatile and fast- 
changing as information technology this 
tendency to embrace the pleasant fiction 
and reject the hard reality is very danger- 
ous. It would be useful if articulate and 
intelligent professionals like Jacob Raab 
worked to discourage rather than foster 
it—L.V. 


NOT CUT-AND-PASTE, BUT NOT BAD 
While Carl Franklin’s CopyTable func- 
tion certainly works as advertised, there’s 
amuch simpler way to copy a table from 
one database to another [Q&A, “Tabular 
Genetic Engineering,” Visual Basic 
Programmer’s Journal, January 1996]. Use 
a SELECT...INTO...IN query: 


Sub CopyTable (dbSrc As Database, _ 
sDestDB As String, sSrcTbl As _ 
String, sDestTbl As String) 


Dim dbTemp As Database 

Dim SQL As String 

Const DB_LANG_GENERAL = _ 
"; LANGID=0x0809 ;_ 
CP=1252;COUNTRY=0" 


" Create destination database if 
" it does not exist 
If Len(Dir$(sDestDB)) = 0 Then 
Set dbTemp = CreateDatabase_ 
(sDestDB, _ 
DB_LANG_GENERAL) 
dbTemp.Close 
End If 


" Copy table into destination 
" database 


SQL = "SELECT * INTO " & sDestTbl 
SOL = SQL &" IN'" &_ 

sDestDB & ""' " 
SQL = SQL & "FROM" & _ 

sSrcTbl & ";" 


dbSrc.Execute SQL 
End Sub 


This method requires substantially 
less code and will likely run much faster 
than explicitly duplicating each field and 
inserting records individually into the 
new table. The downside is that the above 
procedure does not trap and log errors 
as Carl’s function did. 

Phil Weber 
VBPJ Technical Review Board 
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VBAssist 


VBAssist 4.0 from Sheridan 
seamlessly integrates itself both 


VBAssist 4.0 now supports a Customizable 
toolbar that allows you to design a toolbar of your most 
commonly used and favorite VBAssist tools. “Tooltips” 
make the toolbar buttons more descriptive and easier to 
use. The tabbed toolbar conserves space while conveniently 
grouping VBAssist functions. The VBAssist toolbar can also 
float or be docked to Visual Basic. 


visually and functionally to Visual Ae 


Basic, giving you unprecedented 
access to a wide range of design 
tools. Today’s VBAssist makes 

everything in Visual Basic easier 


Control Templates let you save 
groups of controls that can be instantly accessed 
and placed on any form or container. 


Alignment Palette contains over 35 
control alignment functions and includes multiple 
undo and redo 


‘ The Property Assistant is a replace- j Resource Assistant lets you 
than ever before, with more than ment for Visual Basic’s property window. Define create Windows® resources such as bitmaps, 


57 productivity tools designed 


subsets of properties you want to set. View and set icons, cursors and string tables from within 
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than ever before, VBAssist 4.0 is 
completely compatible with 16- 
and 32-bit Visual Basic. Created 
for the professional developer, 


Clipboard History keeps track of 
past clipboard activity and displays a dialog when 
pasting, for you to choose from a list of items 


The Data Assistant lets you 
bind controls to database fields using drag 


and dro 
B Color Palette lets you set color proper- 


ties using standard and custom palettes, RGB sliders, 
hex values or a list of Windows“Systems Colors” 


DB Assistant lets you create and 
edit databases, tables and indexes from within 
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quickly create projects 


and resource usage for quick, 
trouble-free operation. And it 
features a tabbed-toolbar interface 
to conserve space while convenient- 
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LA County jail system 
cuts in-house crime 


| n addition to keeping track of more than 20,000 inmates who 
are awaiting trial, arraignment, or otherwise detained, the 
Los Angeles County Sheriff’s Department is charged with man- 
aging the millions of dollars these inmates bring into the system. 
Using hard currency as the means of exchange fosters inmate 
crimes including extortion, buying contraband from outside the 
jail, and theft. In early 1995, a Cashiering and Jail Store System 
(CJSS), initiated by a team of developers from Integra Technol- 
ogy International Inc., eliminated cash transactions within the 
system and, in the process, cut down on crime. 

Previously, the inmates imprisoned within a network of 10 
jail locations throughout Southern California were allowed to 
carry up to $40 to buy food and supplies. Inventory of goods was 
not automated, the cash register-based system was inaccurate, 
and if the power went down, each register would need to be 
reconfigured. Now, the system is debit and credit based and 
each transaction is tracked through a bar-code system and 
triggered by the new wrist bands worn by all inmates. 

The entire customer cycle—including requirements, testing, 
review, documentation, definitions, and installation—took about a 


Staff locater goes 
beyond plans 


t began as asmall application to print updated floorplans for 

distribution throughout a large law firm in Toronto, Ontario. 
Now it’s a full-blown employee information manager that even- 
tually will make its way to the desktops of all 500 employees at 
Smith, Lyons, Torrance, Stevenson, & Mayer. 

The application, called Staff Manager, displays the location 
of employees on scrollable floorplans and stores information 
about each employee. The Payroll, Human Resources, and 
Information Systems departments can either double-click on an 
employee’s name in a list to view his or her location on the five- 
level floorplan, or double-click on an employee’s name on the 
floorplan to bring up his or her job title, telephone extension, 
home phone number, and other information. 

James Dean, Communications/Programmer Analyst for Smith, 
Lyons, started developing the app more than a year ago, when 
the HR department requested a faster and easier way to modify 
and print floorplans for weekly distribution. They used to pho- 
tocopy existing floorplans, white-out the names where employ- 
ees had left the company or changed locations, write in new 
names, photocopy the floorplans again, and distribute them. 

The company then switched to a CAD program, “but it takes 
10 minutes to print each floorplan because there’s so much 
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year to complete. “Thesystem as awholeis a fairly substantial client/ 
server application talking to a distributed network of SQL Servers 
running on NT, and the actual workstations are running the client- 
side code which is all VB,” says Armand Sperduti, senior vice 
president of solutions services at Integra. The radio frequency- 
based network consists of mobile laptops wheeled through the 
facilities on carts and fixed-location computers throughout the 
various jail complexes. These computers share inmate and inmate- 
account information across seven servers. Using a VC2 app running 
as an NT server, CJSS also ties in to the county’s existing mainframe. 

Three VB applications come through the front end. “Each is 
about 170K a piece. Altogether, there are about 40 forms and 15 BAS 
files that constitute all three applications together,” says Mike Hill, 
one of the developers. The VB apps usean OLEclient written in VC++ 
to perform the network security. 

Currently, the programming team is working with LA County on 
updates and enhancements. “As long as the county is in business, 
we'll continue to provide support,” says Sperduti. —Amy Little 


You can reach Armand Sperduti at armands@midak-int.com. 
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detail,” Dean says. So Dean wrote a VB3 app to replace this 
tedious process. Dean is most proud of Staff Manager’s Print 
feature. He used API calls to do printing, which made the app 
print the plans more quickly than the CAD program did. 
Adding employee information to the app was a natural progres- 
sion, Dean says. He also plans to incorporate user and administra- 
tor privileges to make it available to everyone in the company. 
Having a C background, Dean considered using VC++. But he 
decided on VB because he “didn’t have to reinvent the wheel,” 
he says. “I knew that it would take far too long to create what it 
tookafew months to create in Visual Basic.” —Nina Goldschlager 


You can reach James Dean on CompuServe at 74754,2630. 
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do it 
CONS| 


Tools can do many things. 


Unfortunately, completely elimi- 
nating work is not one of them. 
Still, tools do make work less 
laborious, whether you’re building 
a house or a relational database. 
Should you be building the 
latter, the Microsoft® Access 
Developer’s Toolkit delivers the 
tools you need to get the most 
out of the new, more powerful 
Microsoft Access for the 
Windows® 95 operating system. 
Tools like a new Setup Wizard 
and additional OLE controls, pre- 


built software components you 


PROGRAMMERS SHOP 
(800) 446-1185 


i Microsoft Vv 


Prebuilt OLE 
controls let you 
add power to 
solutions without 
having to 
write all the 
code yourself. 


Pred tx WS 5 Tools for 
incorporating 
enhanced 
replication 
management in 
your solutions. 


Y 


Royalty-free 
license enables 
you to distribute 
Microsoft Access 
solutions to all 
your users. 


Data Replication lets you easily synchronize data between multiple copies of a database. 


Visual Basic® for Applications gives you an improved integrated development environment. 


New wizards make importing, analyzing, and creating databases even easier. 


can plug into your applications. 
Plus, a language reference guide 


and a royalty-free license to dis- 


tribute solutions to all your users. 


By adding enhanced capabilities 
to Microsoft Access applications, 
the Microsoft Access Developer’s 
Toolkit lets you develop and dis- 
tribute better solutions. 

The way we see it, your job is 


to create. Let the tools take care 


EGGHEAD 
(800) 741-4395 


of the tedious stuff. After all, 
they don’t mind. They’re tools. 
To find out more about the 
Microsoft Access Developer’s 
Toolkit and Microsoft Access 
for Windows 95, call us at 
(800) 259-7242, Dept. 7GY, for 
your free Developer Roadmap 
CD, or visit us on the World 
Wide Web at http://www. 


microsoft.com/accessdev. 


STREAM 
(800) 692-2117 


© 1995 Microsoft Corporation. All rights reserved. Microsoft, Visual Basic, and Windows are registered trademarks and Where do you want to go today? is a trademark of Microsoft Corporation. 


Power tools for VB4 


Introducing 


PowerPak™ Professional Edition 


QuickPak® ee 
Professional from Crescent 

Get a head start delivering high-per- 

formance VB4 applications with this 

arsenal of 29 essential custom controls, 

more than 250 DLL routines, and 5 = 
dozens of sample programs. 


RADBench™ 

from Crescent 

Extend the functionality of the 
VB4 IDE with this full assortment 
of productivity tools, including 
alignment controls, bookmarks for 
code, tab settings, and much more. 


XRef™ from Crescent 

View, analyze, and manage your application-in- 
process. Generate lists of key program parameters, 
call-tree reports, and source code listings. View 
properties and events of your custom controls. 


Create resolution independent forms, 
add wizards to your apps, and create 
notebook-style tabs. Resize all the 
controls on your form, parse and scan 
files automatically, and much more. 


SEES z 2 ™ : 
[PoweRalabro VS-OCX™ from VideoSoft 


TrueDBGrid™ from APEX 
The enhanced, full-featured version 
of DBGrid that ships with VB4, 
TrueDBGrid assures that your apps 
will conform to, and benefit from the 
latest OLE and database technologies. 


VSView/OCX™ from VideoSoft 
Get complete control over the look of your 
form—combine text, data, graphics, and 
tables anywhere on a page. Also includes 
rich formatting features. 


Why spend valuable time looking for the best-of-breed-tools for VB4? Crescent has done the 
shopping for you. PowerPak is an all-star line-up of VB4 tools from the leading vendors, with 
integrated documentation, and single-source support at an unbeatable price! Say goodbye to 
hours spent calling different vendors. With PowerPak, one number connects you to a team of 
professional developers who will get you the information you need fast. Try PowerPak for 30 days. 
If you're not completely satisfied, return it to us and we'll refund your money. No questions asked. 


CRESCENT 


mic——Division of Progress Software 


14 Oak Park 
Windows and Visual Basic are registered trademarks of Microsoft Corporation. Crescent, XRef, RADBench and PowerPak are trademarks of Crescent Divi- Bedford, MA 01730 USA 
sion of Progress Software Corporation. QuickPak is a registered trademark of Crescent Division of Progress Software Corporation. VideoSoft, VSView/OCX 
and VS-OCX are trademarks of VideSoft. APEX and TrueDBGrid are trademarks of APEX Software Corporation. All other trademarks referenced are property 617 -280.3000 


of their respective owners. 


VBPJO396B 


Oye on ove ve) ce 6) http://www. progress.com/crescent 


—-yo) ecrescent@progress.com. ©. 617.280.4025 ~— © 800.352.2742 


No More Boring 
Buttons bas 


He Ford once said you could buy his cars in any color 
you wanted—as long as it was black. Similarly, VB allows 
you to have any kind of button you want—as long as it’s 
rectangular. While rectangular buttons work fine for most pur- 
poses, some applications require other shapes, such as tri- 
angles and circles. FarPoint Technologies’ ButtonMaker lets 
you create the buttons of your dreams for those visually pleas- 
ing applications. 

Buttons created in ButtonMaker have all the standard button 
properties and events, so they can easily replace existing VB 
buttons. You can set each button to act as an on/off toggle, or 
regular click and release. Each button can have a separate 
bitmap and/or text for the normal, depressed, and disabled 
states. Buttons can be grouped together and set to behave like 
radio buttons, if desired. 

Buttons are created using segments to define the button 
shape. Buttons can be defined with up to 256 segments, and 
segments (the lines between the segment’s end points) can be 
straight or curved. An ellipse, for instance, may consist of four 
segments, each defining a quarter-circle. Each segment may be 


Dana Cline programs in Visual Basic, writes help files, and reviews 
software tools. CompuServe: 73700,3053 


Roll your own ey 
data eta in VB 


ess, they say, is sometimes more, and ona few occasions I’ve 
found that to be true with the Jet engine at the core of Visual 
Basic’s database handling. It is a prodigious piece of work—rock- 
solid, mature, flexible, willing to take on just about any task. But it’s 
also big. I’ve often wanted to roll my own data control, for example, 
to take advantage of a DBF library wrote years ago. I was willing to 
sacrifice speed and capacity for an app that would fit on one disk, 
but I didn’t have the means to make that decision. With VB4’s 
collections the possibilities doubled—imagine an in-memory data 
control based on collections. My prayers were finally answered by 
Apex’s MyData control. MyData looks and acts just like the Visual 
Basic data control, with one minor exception: it’s an empty shell, 
waiting for you to fill in a few events and manage a couple of data 
structures. What you end up with is a data control looking suspi- 
ciously like VB’s but using your own database engine, with virtually 
all the same events and some well-chosen bonus events and 

properties. 
I must first caution you that this evaluation was based on an 


Tom Campbell has been published widely writing about Visual 
Basic, Visual C++, and Borland Delphi. CompuServe: 75530,3607. 


<2 Button Designer - D: TEESE bin 


defined at de- 
sign time or run 
time. In addi- 
tion, the in- 
cluded Button 
Designer allows 
WYSIWYG but- 
ton design, and 
comes with 16 
predefined but- 
ton shapes. 

Cells define 
rectangular por- 
tions of the 
button’s inte- 
rior,and youcan 
use them to di- 
vide a button 
into multiple 
clickable hotspots. Each cell can contain its own text or bitmap 
in any color or orientation, and the number of cells is limited 
only by the usability of the resulting button. A two-cell button 
could act as an up/down channel changer button would on 
your TV’s remote control, for instance. You can change cell 
definitions at design time or run time, or from the Button 
Designer. 

The included buttons are decent, but ButtonMaker really 
shines when doing complex shapes, such as a hand. The 3D 
effects are stunning. Buttons can have the apparent height of 
Windows 95 buttons, or Windows 3.1 buttons (which are taller). 
The light/dark shading works well on complex shapes. Because 
each cell on a button can have its own bitmap, you could make 
buttons that provide visual feedback to the user. 

ButtonMaker also contains a control that can provide help 
balloons, commonly known as Tool Tips, for any control. Help 


Setting Button Properties is a Snap. Set 
most properties from the button control’s 
property sheets. 


CONTINUED ON PAGE 18. 


early alpha version that was missing some crucial documentation. 
While I was unable to finish the DBF engine! was able to scrutinize 
Apex’s sole example, which supported only integers, but which 
used an array for the database—even more rudimentary than a 
collection. Still, it was easy to see that the possibilities are limitless. 
Reading the sample program’s code I got the same sense of 
excitement] had when I first used Desaware’s SpyWorks, which let 
me write VB code that responded directly to Windows messages, 
bypassing C altogether. Being able to write a database engine in VB 
is just as thrilling. The early documentation I saw implied that Apex 
will make their internal API available to control developers. I hope 


CONTINUED ON PAGE 18. 


F 
fia] | MyData Control 


Use Any Data With Bound Controls. MyData control displays 
a Visual Basic array in bound text boxes and DBGrid. 
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“EVERYONE NEEDS 
VB/RIG 2.0!" 


J.D.Hildebrand VB Tech Journal December ‘95 


Error handling made easy: VB/Rig Pro 2.0 is a 
specialized code-generator that protects your application 
from fatal runtime errors. All it takes is a couple of mouse 
clicks and bang — your code instantly become bullet-proof. 
“Rigging” a VB project automatically creates a global 
error-handling subsystem for your application, and can log 
or e-mail errors that occur in the field. Thousands of VB 
developers now use VB/Rig regularly to make their programs 
more stable and maintainable. 

VB/Rig Pro 2.0 features: 

© Displays all run time errors with a procedure map showing 
where the error occurred, where the error was trapped, and 
the call stack at the time of the error. 

© Improved! Insert or remove error rigging without 
disturbing existing logic, even existing error-handling. 

© Implemented entirely in native VB code. Customize it to 
your needs, and it works with VB4 or VB3, 16 bit and 32 bit. 
NEW! Err-Mail!! Run-time errors can be time-stamped, 
logged and automatically e-mailed directly to you. 
“VB/Rig’s mission is to make runtime error-bandling so 
easy to implement that you'll do it every time, all the time, 
as part of your regular development.” 

VB/Rig Pro 2.0 — only $99.95, complete with Avanti’s 
famous 90 day No Quibble Guarantee. 

Call + 415 329 8999 (International), + 415 327 8722 (Fax) 
http:/Avww.avantisoft.com 


USA TOLL FREE (800) 329 8889 


Avanti Software 


NEW P 
rod cts connie 


No More Boring Buttons... 


balloons can be round, rectangular, elliptical, or cloud shaped. 
Balloons can have one of several different kinds of tails, and you 
can determine where the balloon appears in relation to the 
control it documents. 

All flavors of ButtonMaker (VBX, 
OCX, and DLL) contain the button and 
balloon controls and range in size from 
135K to 270K. A 356-page manual ex- 
plains all properties and events in de- 
tail, and contains atutorial to allow you 

to develop buttons quickly and easily. 
cals, Supports both 16- and 32-bi'de- | Would have preferred the Button De- 
velopment using VBXs, OCXs, and DLLs, : DN ee: i 
Price: $99 signer to be more intuitive in how it 
manages button segments: I was hop- 
ing for an interface more like a drawing 
program. Overall, this product looks to be a welcome addition 
to my toolkit. x] 


ButtonMaker 
FarPoint Technologies 
133 Southcenter Court, Ste. 1000 
Morrisville, NC 27560 
919-460-4551 
Fox: 919-460-7606 

~ Quick Facts: A replacement for the 
standard boring Windows buttons, these 
can be any shape with separate internal 


Availability: now 


Roll your own... 


they make it part of the commercial release. 

Creating your own data control is pretty straightforward. On 
startup, an event called ReadMetaData is fired. This is where 
MyData learns about the database schema. In that event you write 
some values to the Columns collection in the MyData control. The 
Columns collection has an automatically updated Count property 
and, of course, column objects. Columns describe the field names, 
their data types, the maximum number of characters that can be 
typed into them, and whether they are read-only fields. If you loop 
through the Columns collection the ReadMetaData event takes less 
than 10 lines of code. 

Then you write handlers for a few events such as ReadData, 
WriteData, DeleteRow, and so on. The 


MyData control 

Maia Corporation most challenging part is the code for 
4516 Henry St bookmarks, and even that’s a snap. A 
Pittsburgh, PA minimal datacontrol takes only 100 lines 


412-681-4343 

Fox: 800-858-2739 

Quick Facts: MyData control fires 
special Visual Basic events that let 
you provide your own data. 

Price: $149.95 : 
Availability: February 1996 


of code or so, but the more data types 
youhandle, themore (largely duplicated) 
lines you write. I would guess that a full 
control with robust error handling 
wouldn’t set you back more than 1000 
lines. All ODBC datatypes are there, and 
there are also lots of bonus events, such as AddData, DeleteRow, 
WriteData, etc. Likewise there are many new properties, but no 
Database property. (You're replacing it, after all!) 

Hopefully, the finished documentation will have step-by-step 
tutorials for creating both disk- and memory-based controls, and 
Ihopethey document the C/C++ API. MyDatais well designed, and 
if it works as advertised, it will exceed my fondest hopes of being 


able to create my own database engine. | 


Editor’s note: Please send product information to New Products Editor, c/o 
Fawcette Technical Publications, 209 Hamilton Avenue, Palo Alto, CA 94301- 
2500; fax: 415-853-0230. CompuServe: 74774,305. Internet: 74774.305 
@compuserve.com. If you have international distributors of your product, 
please include their phone and fax numbers with your submissions. All 
companies listed are located in the United States unless otherwise noted. 


CREATE HYPERTEXT DOCUMENTS 
TX nfo Artistis an add-on for TX Text-Contral.Itlets you create hypertext documents with the help of TX. This way you can distribute 
electronic manuals, information systems, or documents for CDs and e-mail with a royalty-free viewer. $199, royalty free. 
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Available now. Source code available. 
European Software Connection. Phone: 800-986-6578 or 913-832-2070. Fax: 913-832-8787. 


Products Mids 
Sot Tan ign ect ve oe ad CONTINUED 

CompuServe /Internet /World Wide Web: 71141,3624; 

sales@esconnect.com; http://www.esconnect.com. 


ADD DESKTOP PUBLISHING TO YOUR APP 

TX Publisher is an add-on for TX Text-Control that gives desktop-publishing 
functionality to programs written in Visual Basic. $199, royalty free. Available 
now. Source code available. 

European Software Connection. Phone: 800-986-6578 or 913- 
832-2070. Fax: 913-832-8787. CompuServe/Internet /World 
Wide Web: 71141,3624; sales@esconnect.com; http:// 
www.esconnect.com, 


PC-CHARGE INTERFACE KIT 

PC-Charge Interface Kit makes it easy to integrate PC-Charge into your 
applications. Your applications can process credit cards, ATM/debit cards, and 
check-guarantee services. This kit includes complete specifications on how PC- 
Charge works, along with a VBX and OCX. Requires PC-Charge. $95. VBX 
available now; OCX, first quarter 1996. Source code not available. 

Go Software Inc. Phone: 912-925-4048 or 800-725-9264. 
Fax: 912-927-0214. World Wide Web: http:// 
www.netpath.com/~gosoft/. 


TILT, CROP, FLIP, ROTATE, AND MIRROR 

High-speed image decompression control with outstanding special effects and 
image handling capabilities. It features image tilting, crop, flip, rotate, mirror, 
FAST image decompression and color mapping, fixed palette support with 
dithering, grayscale, and FAST thumbnail display. Displays BMP, JPEG, and PIC 
formats. Includes hotspot editor and stand-alone image compression software. 
$295. Call for availability. Source code not available. 


ImageFX. Phone: 716-272-8030 or 800-229-8030. Fax: 716- 


272-1873. CompuServe: 76327,251. 
VISUAL TELEPHONY DEVELOPER’S KIT 


The Visual Telephony Developer's Kit lets you create computer telephony 
applications. The kit includes TAPI-compliant drivers for Windows 95. Rhetorex 
offers a TAPI Service Provider that supports all three Windows versions. The kit 
also includes samples of Visual and Windows application generators and toolkit 
products offered by our VARs. $1,295. Available now. Source code not available. 
Rhetorex Inc. Phone: 408-370-0881. Fax: 408-370-1171. 
Internet: rhet.info@octel.com. 


BAR CODING SOFTWARE 

This bar coding software can be used with most development tools. The bar codes 
are designed as fonts and are available in Truetype, Postscript, and Hewlett 
Packard softfont format. The bar codes work like standard fonts. In most cases, 
you just assign the font to the field you want bar coded, and the data will appear 
on screen and in printouts as a bar code. Eight types of bar codes are available, 
and each is sold separately: Code 39, Code 128, Code 93, Codabar, Interleaved 
2 of 5, MSI-Plessey, PostNet (US Postal bar code), and UPC/EAN/ISBN. $149 
each. Available now. 

Rivers Edge Corp. Phone: 210-590-9528. Fax: 210-656- 
8993. 


RSTOOLBOX 

RSToolbox is a group of specialty graphical, OLE Custom Controls tools, consisting 
of RSTools and RSPowerTools. RSTools include RSGauge, RSVessel, RSData, 
RSButton, RSSlider, and RSWheel. The RSPowerTools manipulate and control 
other system objects and include RSAnimator, which manipulates and changes 
properties of other objects such as movement, sizing, color changes, and text 
manipulation, and RSEventMaster, which hooks and reacts to system and object 
events. Call for pricing and availability. Source code not available, 
Rockwell Software Corp. Phone: 414-321-8000. Fax: 414- 
321-2211. CompuServe /World Wide Web: 74431,1036; 
http://www.software.rockwell.com. 


UPDATES 


MIGRATING LEGACY CODE 

GUISys/VBSys 3.0is an artifical intelligence-based product for migrating legacy 
applications to Windows-based client/server environments. GUISys automatically 
migrates AS/400, $/3X, or $/390 applications to a distributed presentation 
environment under Windows or 0S/2. VBSys automatically migrates the 
presentation layer to a fully functional Visual Basic application. $13, 500 for first 
developer kit. Available now. Source code not available. 

CST - Client/Server Technology Inc. Phone: 770-677-3080 or 
800-773-9574. Fax: 770-677-3090. Internet: guisys@cst- 


inc.com. 


GENERATE LARGE-SCALE APPS 

DECADMIRE provides a graphical application development environment that lets 
your programming team generate large-scale VB4 applications in Windows 95. 
You can design, define, prototype, generate, test, and deploy client/server 
applications, This version automatically generates the complex code logic 
needed to bridge client and server software into a robust application. It also 
supports the development of integrated OpenVMS and Microsoft Windows NT 
client/server enterprise applications. Call for pricing. Available now. 

Digital Equipment Corporation. Phone: 603-881-0642. Fax: 
603-881-0120. 


SECURE YOUR WAN APPS 

Dunn Systems Secure SQLBase, a secured client/server database engine, is an 
enhanced version of Gupta’s SQLBase. VB developers can create applications 
that use the Internet as a secure WAN. The product incorporates RSA algorithms 


into SQLBase to provide users with secure access to corporate data over the 
Internet. All remote access to the SQLBase data through any TCP/IP network 
is secured. Support is provided for ODBC access and remote database 
management functions over the Internet as well. $1595, for a five-user 
version. Available now. 

Dunn Systems Inc. Phone: 708-673-0900. Fax: 708-673- 
0904. 


ACTION-PACKED CUSTOM CONTROLS 

FXTools/VB Professional Version 3.0 includes nine custom controls for Visual 
Basic that display images, text, shapes, and video. There are 113 main, 
transition, and multipass dissolve effects including wipes, blinds, splits, and 
diagonals. It displays 10 image file formats, and it has scalable hotspots, 3-D 
borders, 3-D fonts, AVI and QuickTime video with effects; WAV and MIDI sound. 
$349. Call for availability. Source code not available, 


The Complete 
Help Authoring Solution 


JOM JedAH dIsHUIN 


WM 100] dyaHUIM 


WM Capp GISHUIN 


Includes both 32-bit 


S6 dHHOg0N 


16-bit versions! 


WinHelp Office™ 95 is the solution you've been looking for if you need 


to easily produce professional Help systems for Windows 95, Windows NT, 


and Windows 3.x. WinHelp Office was designed to make your job easier. Just 


point-and-click for full support of ALL Windows Help features including the 


new advanced features of Windows 95. The included RoboHELP@ 95 comes 


with the SmartHelp™ OLE Control that lets you add context-sensitive Help 


to any application without programming. 


Everything you need to create award-winning Help systems for 


Windows 95, Windows NT, and Windows 3.x, all in one box. 


Call us today for more information and receive the FREE 


electronic guide: Windows 95 Help - What’s New? 


BLGENSIONS 


Blue Sky Software 1-800-571-9767, Int'l 619-459-6365, Fax 619-459-6366 


http://www.blue-sky.com -or- E-mail to info@blue-sky.com 
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NEW PRODUCTS 


CONTINUED programmers with a working knowledge of VB. Topics include the Data 


Control and Data Access Objects; connecting to Access, third-party ISAMs, 
and ODBC-compliant databases; use of functions and properties to open 
databases and tables; and prototyping client apps to meet general GUI 
guidelines. Call for pricing. Available now. 

Grace Technology Institute. Phone: 508-650-3939. Fax: 
508-655-4066. Internet: gracetec@world.std.com. 


GUI DESIGN WITH VB4 

Designing a Graphic User Interface with VB4 teaches programmers how to 
make appropriate GUI design decisions. Students will understand and be 
able to implement effective windows management, compliant with Windows 
3.x, Windows 95, and Windows NT. The course is intended for application 
developers, prototypers, and analysts who are new to Visual Basic. Specific 
topics include Microsoft Windows interface guidelines, prototyping, 


ImageFX. Phone: 716-272-8030 or 800-229-8030. Fax: 716- 
272-1873. CompuServe: 76327,251. 


CLIENT/SERVER DEVELOPMENT 
Client/Server Development Using Visual Basic V4 provides experience in 
developing client/server applications with various database servers to 


There's no faster, better 
way to develop Visual Basic 
applications than this. 


Want to develop better quality Visual Basic 4 applications, faster than ever 
before? You can...by reusing what's already been done. And now, with VB 
AppFramework (AFW), 


reusing your best work is 


as easy as anything you'll 


; ever do in VB. 
, & AFW lets you capture Tem- 
{= Functions E && _ plates, Styles and Frame- 
e Styles Ee of 


Si renews 


works from VB compo- 


nents as you work, then instantly apply them to 
speed up your work on any project, anytime. 


AFW goes beyond source code control and file management systems. You 
can capture Templates for forms and modules, controls and menus (with 
methods), control and menu collections, and functions or code blocks. 
You can capture Styles for forms and controls. And build Frameworks that 
help you start new projects or add to ones already under way. You can 
even Clone forms, controls and Styles as you work. 


AFW Libraries are sharable and portable. That makes AFW ideal for indi- 
viduals, team developers, and even consultants who need reusable 
resources wherever they go. AFW even ships with a professional Library 
for instant productivty right out of the box. 


Best of all, AFW is integrated directly with VB. It's friendly, easy to learn, 
and never clutters, slows down or restricts your VB work in any way. 
Finally, AFW actually grows in value 


as you use it, because the more 
you reuse, the more productive 


you become! MSRP just $199. 


VB AppFRAMEWORK 
1 -800-743-1 400 ° FAX 303-743-1400 


http://www.semiotix.com 


10620 E Bethany Dr, Aurora CO 80014-2602 


‘SEMIOT x 


sYSTEMS———— 


iin 8 
fe 


we 


programming language, and managing multiple forms. $595 (group 
discounts, customized and on-site seminars available). Available now. 
Grace Technology Institute. Phone: 508-650-3939. Fax: 
508-655-4066. Internet: gracetec@world.std.com. 


OBJECT PROGRAMMING WITH VB4 

Object Programming with Visual Basic 4is a training guide for corporate in- 
house developers and programmers at all levels who want to combine Office 
for Windows 95 and Visual Basic 4 to create customized business applications. 
It teaches you object-oriented techniques for building automated applications 
of the type usually developed by forms-based development systems. By 
Joel Dehlin and Matt Curland. ISBN: 1-55615-899-8, 512 pages with one 
CD. $39.95, U.S.; $53.95, Canada. Available March 1996. Source code 
available. 

Microsoft Press. Phone: 800-MSPRESS. Fax: 800- 
PRIORDER. CompuServe/World Wide Web: GO MSP; http:/ 
/www.microsoft.com/mspress. 


==] TRAINING/ 
C ONFERENCES 
ONINE COMPUTER TRAINING 
Damar Enterprises has been providing Microsoft Authorized technical training 
on The Microsoft Network. They offer certified trainers along with self-study 
courseware. You can take courses in Visual Basic 3.0, Visual Basic 4.0, and 
Windows NT 3.51. Courses use computer-based-training methods and feature 
online support. Courses are also offered on CompuServe (GO TRAINERS). 
Call for pricing and availability. 
Damar Enterprises. Phone: 602-818-6260. Internet / 


CompuServe: dtperko@msn.com; dave@damar.com; 
76275,1170. 


VB4 PROGRAMMING COURSE 

Learn the general programming concepts of Visual Basic 4.0 and how to 
integrate applications into the Windows environment through the use of 
database components, DDE, OLE, and DLLs in this five-day course. The 
course includes labs that reinforce the concepts taught. The 1996 dates for 
the Denver, Colorado, location are: April 15-19, June 17-21, and August 
19-23. $1,495. Call for availability. 

Batky-Howell. Phone: 303-689-9090 or 800-868-2202. 
Fax: 303-689-9904. World Wide Web: http:// 
www.batky-howell.com. 


VBCD GOES MONTHLY 

This monthly CD-ROM contains electronic versions of every VBPJ and BasicPro 
back issue indexed for easy retrieval; the Catalog on Disk database, a 
comprehensive directory of every third-party add-on product for the entire 
family of Microsoft development tools, including Visual Basic, Visual C++, 
Access, BackOffice, Visual FoxPro, and OLE controls; code, sample applications, 
and shareware. $99.95 for a one-year subscription. Available now. 
Fawcette Technical Publications. Phone: 415-833-7100 or 
800-848-5523. Fax: 415-853-0230. World Wide Web: 
http://www.windx.com. 


BECOME VB CERTIFIED 

VB-Cert is a Windows-based program that gives timed simulations of the Visual 
Basic Application Development exam given by Microsoft. VB-Cert pinpoints your 
weak areas and fully explains the reasoning behind the answers. VB-Cert also 
serves as a refresher prior to starting a new VB project. It includes study outline 
and a money-back-if-you-don't-pass guarantee. $129, plus $4 shipping and 
handling. Available now. Source code not available. 

Transcender Corp. Phone: 615-726-8779. Fax: 615-320- 
6594, 


VISUAL BASIC INSIDERS’ TECHNICAL SUMMIT ‘96 

At the Visual Basic Insiders’ Technical Summit (VBITS), you'll learn about 
OLE Automation and OLE controls; DBMS development; accessing the Windows 
API; tips, tricks, and techniques for use with both Visual Basic for Windows 
and Visual Basic for Applications (VBA), user interface design; client and 
host development, multiple-document interfaces, graphics, animation, and 
bug fixes. The sessions are aimed at the professional developer. The 
conference locations and dates are: San Francisco, California (February 12- 
14); London, England (April 10-12); Tokyo, Japan (May 15-16); New York, 
New York (June 24-26); Orlando, Florida (September 25-27). VBITS is 
sponsored by FIP and Microsoft Corp. Call for more information and an 
advance registration kit. 

Fawcette Technical Publications. Phone: 415-833-7100 or 
800-848-5523. Fax: 415-853-0230. World Wide Web: 
http:/ /www.windx.com. 
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guidance, an intrepid 
developer can unlock 
the secrets of the 
Win3S2 Registry. 


brain, and eyes of Windows, the reg- 

istry would be the memory—both 
long and short term. OK, maybe this meta- 
phor is a bit weak, but the point should be 
obvious: the registry is a critical compo- 
nent of a well-functioning system and 
you’re not going to get very far without it. 

The registry is lightly documented and 
not well understood. Programming it can 
be similar to the old neurological tech- 
nique of zapping part of the cerebral 
cortex with an electrode and seeing « 
what happens: the patient may re ‘G 
member a baseball game or experi-ence 
a war-related flashback. In Windows, you 
may enable a cool new feature or render 
your system unbootable. But it’s the thrill 
of the hunt that makes it so exciting. 

After a brief introduction to get our ter- 
minology straight, I'll skip the fundamen- 
tals of the registry—MSDN would be an 
ideal place to find this information—and 
leap into advanced aspects. 

Along the way I'll note a variety of 
thing you can take advantage of immedi- 


| f USER, Kernel, and GDl are the heart, 


Keith Pleas is an independent developer, 
author, and trainer. He is the author of the 
forthcoming book, Visual Basic Tips & 
Tricks, from Addison-Wesley. He can be 
reached on Compu-Serve at 71333,3014 (from 
the Internet: 71333.3014@compu-serve.com). 


applications, 


BY KEITH PLEAS 


ately: some of them are particular to the 
new Windows shell (first delivered on 
Windows 95 but currently in beta on Win- 
dows NT), some work only with NT (also 
known as “Microsoft’s real operating sys- 
tem”), and some will work for everybody. 
So, grab your tools (primarily a copy of 
RegEdit) and prepare for an exciting round 
of hacking the registry. 

The registration database, commonly 
called the registry, contains a substantial 
amount of data about the computer and 
users. It includes computer data such as 
hardware, the OS, and installed 


and user information such as their desk- 
top settings and customization prefer- 
ences. The registry stores data ina hierar- 
chically structured tree. Each node in the 
tree is called a key. Each key can contain 
additional keys called subkeys (see Figure 
1). Keys are composed of printable char- 
acters and cannot include backslashes 
() or wildcard characters (* or ?). Sev- 
eral predefined keys, represented with 
uppercase words separated by under- 
scores, can be accessed using numeric 
constants. These keys are always “open,” 
so it’s not necessary to use the RegOpen... 
functions on them. It’s important to note 
that the root key for machine information 
HKEY_LOCAL_MACHINE (HKEY_CLASSES _ 
ROOT and HKEY_CURRENT_CONFIG map 
to subkeys) and the root key for user infor- 
mation is HKEY_USERS (HKEY_CURRENT_ 
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USER also maps toa subkey). Keys beneath 
the root are referenced by building a string 
key by concatenating each node together, 
separated by backslashes. 

Each key also contains data stored in 
values: a key may have no values, a de- 
fault value, or any number of named val- 
ues in addition to the default. The data in 
the values may be in a variety of forms, 
though text and binary data types are by 
far the most common. While key names 
and value names are never localized, text 
data often is. Using the Windows 95 
RegEdit utility shows you a much 
compacted view of the registry in- 
‘fcluding the root keys, several 

subkeys, a default (text) value, and a 
amed (binary) value (see Figure 2). 
Note that Windows NT has a similar but 
slightly different structure: it omits HKEY_ 
CURRENT_CONFIG and substitutes asome- 
what analogous HKEY_PERFORMANCE_ 
DATA for HKEY_DYN_ DATA. 


SPELUNKING THE REGISTRY 
Avariety of commoncomponents 
can be found in the registry, es- 
pecially if they have anything to 
do with OLE. Here are some examples so 
you'll know what you’re looking at when 
you go spelunking with RegEdit. 

Creatable OLE classes, provided by 
OLE servers, must be in the registry. Each 
class is registered separately in the 
HKEY_CLASSES_ROOT\CLSID key under 
its CLSID and must, at minimum, have 
enough information for the OLEsystem to 
locate and start the server. For example, 
Access registers the Application object 
with the key name on the left and the 
default value on the right: 


{B54DCF20-5F9C-101B- 
AF4E 00AA003FOFO7) 

InprocHandler32 

LocalServer32 

ProgID 


Microsoft Access Database 


ole32.d11 
C: \MSOFFICE\ACCESS\MSACCESS . EXE 
Access.Application.7 


Mu Computer 

HI HKE'Y_CLASSES_ROOT 

- 4289 HKEY_CURRENT_USER 

EP +O HKE‘Y_LOCAL_MACHINE 
=I {3 Config 
B&Q 0001 
{J Enum 
HQ hardware 
FQ Network 
AHS Security 
Gt Oo SOFTWARE 

{<Q Classes 

i {SQ Description 

F-C9 Microsoft 

fq ODBC 

| BHg scc 

' GHEY System 

EI a HKEY_USERS 

| EL Default 

: {Q) keithp 

fe) HKEY_CURRENT_CONFIG 

f-(9 HKEY_DYN_DATA 


FIGURE 1 Related Entries in the Registry. Expanded (Win95) 
registry keys depict how root keys map to major subkeys 
for current user, classes, and current configuration. 


OLE controls, being specialized in-process OLE servers, must 
bein the registry. Ifan OLE controlis referenced by an application 
but is notin the registry, it can autoregister itself if the system can 
locate it by searching along the normal DLL search path. 

OLE controls are registered as classes and can also be found 
in the HKEY_CLASSES_ROOT\CLSID key by referencing their 
CLSID. For example, the PicClip control that ships with VB4 has 
the following registry entries: 


27395F85-0C0C-101B-A3C9-08002B2F49FB} PicClip Control 
Control 

InprocServer32 C: \WINDOWS\SYSTEM\PICCLP32 .0CX 
nsertable 
MiscStatus 

ProgIDPicClip.PictureClip 

‘ool boxBitmap32 C: \WINDOWS\SYSTEM\PICCLP32.0CX, 1 
TypeLib {27395F85-0C0C-101B-A3C9-08002B2F49FB} 
Version 1.0 


The Control key is used when dialog boxes like the OLE Insert 
Object dialog or VB4’s Custom Controls dialog is displayed with 
the Controls box checked. InprocServer32 contains the fully 
qualified path to the control. 

ProgID contains the so-called “friendly” name, which can also be 
found in a separate key under HKEY_CLASSES_ROOT: this separate 
key contains a pointer backtothe CLSID whereall the information for 
thecontrolis maintained. The Insertable key behaves similarly to the 
Control key, though it may be duplicated under the ProgID key for 
backward compatibility with OLE 1.0 servers. 

The type library for a control is indicated in the TypeLib key. 
Type libraries are stored separately in the registry under their 
own GUIDs in the HKEY_CLASSES_ROOT\TypeLib key. The 
entries for the PicClip control’s type library are: 


{27395F85-0C0C-101B-A3C9-08002B2F49FB} 

1.0 Microsoft PictureClip Control 
0 

win32 C:\WINDOWS\SYSTEM\PICCLP32.0CX 

FLAGS 2 

HELPDIR C: \vB4 


Note that the type library itself can be stored as a separate 
file on disk (typically with a TLB or OLB extension) or attached 
as aresource to a DLL or EXE. Because OLE controls are in fact 
DLLs, their type libraries are most often stored with the 
control itself. 

The HELPDIR key is notable because it points to the fully 
qualified location for the accompanying WinHelp file containing 
additional programming documentation about the control. This 
location can obviously vary by installation and is typically deter- 
mined when the controlis first installed: ifthe WinHelp file is moved 
the link can obviously be broken. 

Licenses, such as those used by OLE controls, are also 
commonly stored in the registry. They can be found under the 
HKEY_CLASSES_ROOT\Licenses key, where you'll also find 
the warning that “Copying the keys may be a violation of 
established copyrights.” No kidding. Anyway, each license is 
stored under its own GUID. This example from my registry 
database has both design and run keys (with the key values 
changed, naturally): 


{B54DCF20-5F9C-101B-AF4E-00AA003FOF07} 
Retail 
Runtime 


abedefghijklmnopgrstuvwxyzabcdefghij 
abcdefghijklmnopgrstuvwxyzabcdefghij 


VB4 itself uses this technique: when it’s installed it merges the 
contents of one of the three REG files (for Standard, Professional, 
and Enterprise editions) into the registry. 

Finally, the registry contains information about remoted OLE 
servers in both their local and remote configurations. Like the other 
OLE object described here, this VB4-created OLE Automation 
server registers a Clerk class under its own GUID in the 
HKEY_CLASSES_ROOT\CLSID key. Of course, VB4 handles all the 
registration automatically and it’s typicallynot necessary to modify 
these entries directly. 

RunningtheRemote Automation Connection Manager (RacMgr32) 
utility included with VB4 Enterprise Edition adds additional keys for 
a remote machine name, RPC protocol, and RPC authentication 
level. When run locally, this particular class is registered as: 


{8435CD47-D6BE-11CE-A842-00AA00688747)} 


_AuthenticationLevel d 

_NetworkAddress NT 

_Protocol Sequence neacn_ip_tcp 

InprocHandler32 OLE32 DLL 

LocalServer32 D:\PROJ\MSJ\CAR RENTAL\RENTAL OBJECTS. EXE 
ProgID Rental0bjects.Clerk 

TypeLib {8435CD4E-D6EB-11CE-A842-00AA00688747} 


When the class is remote, RacMgr32 changes the registration 
entries to: 


{8435CD47-D6BE-11CE-A842-00AA00688747} 


_LocalServer32 D:\PROJ\MSJ\CAR RENTAL\RENTAL OBJECTS. EXE 


AuthenticationLevel 2 

InprocHandler32 OLE32. DLL 

InprocServer32 C: \WINDOWS\SYSTEM\autprx32.d11 
NetworkAddress NT 

ProgID RentalObjects.Clerk 

ProtocolSequence ncacn_ip_tcp 

TypeLib {8435CD4E-D6EB-11CE-A842-00A00688747} 
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FIGURE 2 


Notice how the LocalServer32 key gets renamed (actually, 
keys cannot be renamed, so it is destroyed and re-created) and 
an additional InprocServer32 key is created. This new key 
points to the remote automation proxy on the local machine, 
initiating a conversation with the AutMgr utility running on the 
remote machine. 

Of course, you'll never want to touch these registration entries 
directly. In addition to using RacMgr32, we can also call the RacReg 
OLE Automation server in code to examine and change server 
settings. To do so add a reference to the RacReg32.DLL, create a 
RacReg.RegClass object, and use the GetAutoServerSettings func- 
tion and SetAutoServerSettings method. 

Unfortunately, the documentation for these functions is alittle 
obscure: it’s only found in the ReadMe file that ships with VB4. But 
it’s pretty obvious how the RacReg32 server reads/writes the 
registry settings shown in this function prototype: 
object.SetAutoServerSettings (Remote, [ProgID], [CLSID], _ 
[ServerName], [Protocol], [Authentication]) 


A side benefit of using the RacReg.RegClass object is that 
Microsoft’s VB group promises that your code will be upwardly 
compatible with future versions of VB, which will support true 
Networked OLE: they’! do the work of encapsulating the changes 
so that you don’t have to change your code. 


USING REGISTRY FUNCTIONS 


The Win32 API provides a function group of 26 APIs, many of 
them with both “A” (ANSI and “W” (Wide, or Unicode) ver- 
sions, for working with the registry. Five of the 26 APIs are 


vents chemes 


Keys to the Windows Registry. The hierarchical structure of the registry consists of keys and subkeys. The associated values 
for each key can be named (text) or a non-string data type (binary). 


provided for backward compatibility only and shouldn’t be 
used (the corresponding ...Ex functions, which support named 
values and access to keys other than HKEY_CLASSES_ROOT, 
should be used instead). 

Rather than torture you with a complete list of the APIs, I’ll 
point you to a couple of useful samples that highlight their 
implementation such as the RegTool sample that ships on the 
VB4 disc. The RegTool sample is buried down in the \Tools\ 
Dataex32\Source\Regtool subdirectory and has areusable class 
with routines for creating, updating, and deleting keys. Unfortu- 
nately, while it can read both string and numeric (dword) data, 
it can only write strings. 

Amuch better example can be found in the fileREGVB4.ZIP in the 
Magazine Library of the VBP/ Forum on CompuServe. Written by 
Don Bradner, VBPJ Forum Section Leader of the “32-Bit Bucket,” 
REGVB4 is a handy VB4 version of RegEdit that has well-commented 
source code for reading and writing both string and numeric values. 

Several of the registry functions deserve a bit more com- 
ment. While we do not yet have built-in support for a distributed 
registry (where part or all of your registry is stored on another 
machine), the RegConnectRegistry function can be used pro- 
grammatically to connect to remote registries and get/set val- 
ues from their registries. They can connect only through the 
root keys (HKEY_LOCAL_MACHINE and HKEY_USERS), but be- 
cause of the subkey mappings to HKEY_CURRENT_ 
USER, HKEY_CLASSES_ROOT, and HKEY_CURRENT_CONFIG 
this isn’t a major limitation. 

There are also a few differences between the Win95 and WinNT 
implementations of the registry functions. Of course, Win95 knows 
nothing about security, so Get/SetKeySecurity aren’t implemented 
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onthat platform. Also, while Win95 does implement QueryInfoKey, 
it doesn’t track the last write time, so don’t be surprised when the 
FILETIME structure comes up empty. Another thing to watch out 
for, particularly if you develop under Win95, is that RegDeleteKey on 
that platform deletes key and descendants, whereas on NT it can 
only delete keys that have no subkeys. 

Because of its architecture, Win95 has very limited support for 
kernelsynchronization objects, and thus RegNotifyChangeKeyValue 
is not supported at all. Win95 also doesn’t implement 
RegRestoreKey, which can be worked around tediously by writing 
codeto re-create the keys or, mucheasier, by using a REGEDIT4file. 

Interestingly, RegQueryMultipleValues is only implemented on 
Win95 (thoughits primary value appears to be as acoding shortcut). 
Finally, if you must store Unicode datain the Win95 registry you must 
store it as REG_BINARY, because Win95 is an ANSI system. 

It’s also worth pointing out that VB4 includes built-in func- 
tions for working with the registry, though they only work with 
information from a specific location in the registry: 


HKEY_CURRENT_USERS\Software\VB and VBA Program _ 
Settings\<program name> 


I’ve seen a number of people experience problems with the 
built-in VB functions.GetSetting and GetAllSettings are functions, 
but SaveSetting and DeleteSetting are statements and thus don’t 
use parentheses. While SaveSetting and DeleteSetting were origi- 
nally specified as functions, later they became statements. 


IMPORT DATA INTO THE REGISTRY 


It’s common to use registration (REG) files for importing data 
into the registry. REG files have two formats: REGEDIT and 


PLC-MIMI-OCX 


Modular MMI OCX Tools 


NO Runtime Fees 
NO Hardware Keys 
32-bit Power 
30 Day Money Back 
Guarantee 
e Guaranteed 

Lowest Prices 
e Continued 
VBX Support 


Call today for 


your FREE As low as 
Development $ 49 © 
Kit w/ 30 min. 

Runtimes 


Automated Solutions, Inc. 
1636 Putnam Way, Petaluma, CA 94954 


800-410-4632 or 707-578-5882 


26 MARCH 1996 Visual Basic Programmer’s Journal 


Q Reskit35 
{E4 SystemDB 


FIGURE 3 Adding the TXT File Type to the Explorer. This view of 
the New menu in the Win95 explorer is fairly typical, 

except that by using the registry, ladded the TXT file type to the menu. 

Selecting it launches Notepad, the file associated with TXT files. 
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you should use the Reglni utility from the NT Resource Kit. 
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Visual Basic DLLs are made S237 
easy using Visual DLL. And now Visual DLL 


includes both 16- and 32-bit versions! 
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PIR. import/export existing RTF 
text files. VB HelpWriter now 


a ie includes spell checking. NEW! 


Supports VB4 and WIN9D! 
Prod# B360-0101 


htlp://www.mindspring.com/~founn/teletech.himl 


$88 


Data Widgets™ 2.0 


From Sheridan Software Systems 


Sheridan. Bound 


Data 
Widgets 2.0 


Microson 
Visual Basic 


Data Widgets™ 2.0 is a set of custom 
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your database applications. Features include 
the fully editable bound DataGria™, 


DataCombo, the 
SN) & 
$98 
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RoboHELP, 95 
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| macros; plus all the power and S428 
: ease of use of Microsoft Word. cS 
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Help-to-HTML™ Kit 
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LEADTOOLS 
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200 times! It's a complete 

imaging library that is easy $238 
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SpyWorks 


From Desaware 
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more! With SpyWorks custom controls you will 
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Tap into the full power of 
Windows. 


$8 £22MLOLE Control Edison |, 
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FIGURE 4 Adding the Test VB Finder to the Find Menu in Explorer. The registry structure for dynamically added Find items illustrates 
how simple it is to add items to the menu. A modified Find Menu in the new shell’s Explorer show an entry added by MSN as 
well as two custom entries described here. It’s just as easy to add an entry for something like Yahoo for finding files on the Internet. 


CONTINUED FROM PAGE 26. 
This shows the contents ofa trivial REG file using the old format: 


REGEDIT 
HKEY_CLASSES_ROOT\.txt = txtfile 


And, this shows this new format (with a named value): 


REGEDIT4 
[HKEY_CLASSES_ROOT\. txt] 
@="txtfile" 

"Content Type"="text/plain" 


If you distribute a REG file with your application, be aware 
that Setup Toolkit has somewhat limited support for this. You 
can add a REG file with the Add Files button and the Setup 
Toolkit will register those keys on the user’s machine. However, 
you are limited to embedding relative paths and there’s no 
automated support for uninstalling the REG file entries. 

If you’ve been following along on your machine, your registry 
might be getting a little wonky. It’s not uncommon for your 
registry to get whacked: hacking around manually just tends to 
accelerate this process. Eventually, you’re going to want to use 
the little-known RegClean utility (16- and 32-bit) that ships with 
VB4 and is located in the \Tools\PSS subdirectory. It can 
correct a number of these problems in your registry: 


¢ Mismatched GUID in TypeLib. 

¢ Missing TypeLib GUID. 

© Missing CLSID for ProgID. 

e Useless NumMethods or Baselnterface keys. 
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e Invalid ProglID key. 

¢ Missing OLE key. 

e Wrong value for OLE key. 

¢ Missing file. 

¢ Empty subkey. 

¢ Conflicting local/remote keys. 

¢ Improper InprocServer registration. 

e Server isn’t AUTPRX16.DLL/AUTPRX32.DLL. 
e Differing server paths. 

° Missing InprocServer key. 


RegClean also gives you the option of creating a pending change 
file or just letting it rip and make the changes for you (guess 
which one! chose). 


EXTENDING THE NEW SHELL 

If you’ve selected New from the File menu within the Windows 
95 Explorer, after what seems like an inordinate delay you've 
seen a cascading menu (see Figure 3). 

The shell is searching through the registry looking for valid 
file extensions (those beginning with “.”) that have a subkey of 
ShellNew. Each time it finds one, it reads the value in the 
extension’s key to determine the ProglID, looks up the ProgID, 
and adds the value of that key to the menu. 

For example, to add the TXT item to the menu shown in 
Figure 3, I added the ShellNew key to the CLSID key for “.txt” 
files: 


HKEY_CLASSES_ROOT\.txt = txtfile 
Shel lNew 
CONTINUED ON PAGE 34. 
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Dim CRLF As String 
Dim QT As String 
Dim sFile As String 
For x = 1 To Len(txtFile) ‘Double \\ 
If Mid$(txtFile, x, 1) = "\" Then sFile = _ 


sFile & "\" 
sFile = sFile & Mid$(txtFile, x, 1) 
Next x 


CRLF = Chr$(13) & Chr$(10) 

QT = Chr$(34) 

TEXTES CI Pits erie, 

txtScript = "REGEDIT4" 

txtScript = txtScript & CRLF & "[HKEY_LOCAL_MACHINE\_ 


SOFTWARE\Microsoft\Windows\CurrentVersion\explorer\_ 

FindExtensions\Static\" & txtShort & "]" 

txtScript = txtScript & CRLF & "@" & QT & _ 
txtGUID & QT 

txtScript = txtScript & CRLF & "[HKEY_LOCAL_MACHINE\_ 
SOFTWARE\Microsoft\Windows\CurrentVersion\_ 
explorer\FindExtensions\Static\" & txtShort & _ 
"\0]" 

txtScript = txtScript & CRLF & "@-" & QT & _ 
txtDescription & QT 

txtScript = txtScript & CRLF & "[HKEY_LOCAL_MACHINE\_ 
SOFTWARE\Microsoft\Windows\CurrentVersion\_ 
explorer\FindExtensions\Static\" & txtShort & _ 
"\0\DefaultIcon]" 

txtScript = txtScript & CRLF & "@" & QT & sFile & _ 
Hee Oat ae OT, 

txtScript = txtScript & CRLF 

txtScript = txtScript & CRLF & _ 
"THKEY_CLASSES_ROOT\CLSID\" _ 
& txtGUID & "\FindCmd]" 

txtScript = txtScript & CRLF & "@=" & QT & sFile & QT 

txtScript = txtScript & CRLF & _ 
"THKEY_CLASSES_ROOT\CLSID\" _ 
& txtGUID & "\InprocServer32]" 

txtScript = txtScript & CRLF & "@" & QT & _ 
"FindExt.d11" & QT 

txtScript = txtScript & CRLF & QT & _ 
"ThreadingModel" & QT _ 
& "=""& QT & "Apartment" & QT 

txtScript = txtScript & CRLF 


LISTING 1 REGEDIT4 Script Generation. This script is pretty 
standard string manipulation code, with one exception. 
Note the required doubled backslashes and trailing blank line. 


CONTINUED FROM PAGE 30. 
which, when accessed by the shell, was translated into the: 
HKEY_CLASSES_ROOT\txtfile = TXT 


Of course, the point of this isn’t that you can launch Notepad 
(though that is somewhat useful), but that you add your 
program to the New item from your users File menu with very 
little effort. 

The shell can be extended in many other ways. For example, 
you can add a destination application to the Send To menu for all 
Explorer items by placing a shortcut to the destination applica- 
tion in the \Windows\SendTo folder. I suggest you create a 
shortcut in the \Windows\SendTo directory for RegSvr32.EXE. 
Heck, you don’t even have to run RegEdit to do this one. 

You may have clicked on files in the shell that don’t have 
any extension: the resulting dialog is annoying but at least you 
can associate the file with a particular application. Unfortu- 
nately, that association doesn’t “stick” and you have to do this 
every time. Files without an extension are of class “.” and you 
must manually add this type to the registry. You can either add 
a single key that points to whatever (for instance) a “txtfile” 
might be: 


HKEY_CLASSS_ROOT\. = "txtfile" 
or you can enter your own class as in this example: 


HKEY_CLASSS_ROOT\. = "none" 
HKEY_CLASSS_ROOT\none\DefaultIcon = "notepad, 1" 
HKEY_CLASSS_ROOT\none\shell\open\command = “notepad.exe "$1."" 


If you just want to adda single menu command to the context 
menu of a specific file type, you can use a similar technique 
method: these two entries will add an Edit menu item to VB 
project (VBP) files and load them into Notepad: 


HKEY_CLASSS_ROOT\VisualBasic.Project\shell\Edit = "" 
HKEY_CLASSS_ROOT\VisualBasic.Project\shell\Edit\command = "notepad.exe "$1."" 


EXTENDING THE FIND MENU 

The new shell can be extended in a number of ways using, not 
surprisingly, a mechanism called shell extensions. Shell exten- 
sions are implemented as specialized DLLs that create OLECOM 
objects and support specific OLE interfaces. One example is the 
built-in “Files or Folders...” and “Computer...” menu items found 
on the Find submenu. While it’s possible to add to this menu, 
just as MSN does with the “On The Microsoft Network...” item, 
shell extensions cannot currently be written in VB. 

Fortunately, Jeff Richter has written a custom FindExt.DLL 
that encapsulates the necessary functionality and allows at- 
tachment of any program to the Find submenu (see Figure 4). 
You generate custom CLSIDs that point to this DLL: when one is 
invoked, the DLL looks up the associated command line and 
executes it. This compiled DLL is included with the sample code 
for this article available on VBP/’s Development Exchange on 
CompuServe (GO WINDX), The Microsoft Network (GO WINDX) 
and the World Wide Web (http://www.windx.com) and can be 
freely distributed. Richter will be writing about and publishing 
the source code later this year. 

Extensions to the Find submenu are stored in the registry, 
buried in the HKEY_LOCAL_MACHINE\SOFTWARE\ 
Microsoft\Windows\CurrentVersion\explorer\ 
FindExtensions subkey. Extensions stored at that level are loaded 
automatically when the Explorer is first loaded (normally the 
shell boots when Windows 95 is first loaded). The Static subkey 
beneath that contains extensions that are loaded dynamically: 
they are invoked when the user selects the item on the Find 
submenu. This is where you should put your custom find utilities. 

To do so you need to create three additional nested subkeys: 
the extension that points to the CLSID of the InProc server, the 
menu text, and the menu icon. The first item to add is the 
extension that points to the CLSID of the InProc OLE server. 

The name of this key (InetFind, MSNFind, and VBFind in the 
figure) is unimportant: Windows never displays it and the 
submenu items are actually drawn from the registry in the order 
they were added, not alphabetically. The value of this key is the 
text version of a CLSID that points to FindExt.DLL, in this case. 
Next, add the menu text itself (including an accelerator key if 
desired). The name of this key must be “0.” 

Finally, add the icon to be displayed in the menu, which has 
a value that includes the file name of the executable and the 
index of the icon (typically zero) to be used. The name ofthis key 
must be “DefaultIcon.” 

To see the new menu item, it’s necessary to restart the 
Explorer. You can either restart Windows 95, which is slow and 
inconvenient, particularly if you have multiple applications 
open, or you can shut down and restart the shell. To shut down 
the shell, choose “Shutdown” from the Start menu and, when 
you see the “Shut Down Windows” dialog box, hold down the 

CONTINUED ON PAGE 38. 
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Declare Function RegNotifyChangeKeyValue Lib _ 
"advapi32.d11" _ 
(ByVal hKey As Long, ByVal bWatchSubtree As Long, _ 
ByVal dwNotifyFilter As Long, ByVal hEvent As Long, _ 
ByVal fAsynchronus As Long) As Long 

Declare Function WaitForSingleObject Lib "kernel32" _ 
(ByVal hHandle As Long, ByVal dwMilliseconds As _ 
Long) As Long 

Declare Function CreateEvent Lib "kernel32" Alias _ 
"CreateEventA" (IpEventAttributes As Long, ByVal _ 
bManualReset As Long, ByVal bInitialState As Long, _ 
ByVal 1pName As String) As Long 

Declare Function CloseHandle Lib "kernel32" (ByVal _ 
hObject As Long) As Long 

Public Const HKEY_CLASSES_ROOT = &H80000000 

Public Const REG_NOTIFY_CHANGE_ATTRIBUTES = &H2 

Public Const REG_NOTIFY_CHANGE_LAST_SET = &H4 

Public Const REG_NOTIFY_CHANGE_NAME = &H1 

Public Const REG_NOTIFY_CHANGE_SECURITY = &H8 


Private Sub cmdRegistry_Click() 

Dim 1Change As Long 

mhEvent = CreateEvent(0&, False, False, vbNullString) 

1Change = RegNotifyChangeKeyValue_ 
(HKEY_CLASSES_ROOT, True, _ 
REG_NOTIFY_CHANGE_NAME, mhEvent, True) 

tmrRegistry.Enabled = True 

Me.Caption = "Waiting for registry change..." 


End Sub 


Private Sub tmrRegistry_Timer() 
Static 1Signal As Long 
Static 1Result As Long 


1Signal = WaitForSingleObject(mhEvent, 0&) 
If 1Signal = 0 Then 
Me.Caption = "Registry Changed" 
tmeRegistry.Enabled = False 
1Result = CloseHandle(mhEvent) 
End If 


End Sub 


LISTING 2 Declarations and Code for Handling Registry 
Change Notification. The cmdRegistry_Click subroutine 


creates the event object, passes its handle to the system signalling 
when the registry changes, and starts the polling timer. Details about 
Registry Change Notification messages are shown in Table 1. 


CONTINUED FROM PAGE 34. 


Ctrl-Alt-Shift key combination and click on the “No” button. This 
leaves you in something like the old shell, where pressing Ctrl- 
Escape brings up the Task Manager, from which you can select 
“Run” from the File menu and restart Explorer. 

Although the menu item is visible at this point, it won’t 
actually do anything. To make it work, you must add the CLSID 
to the HKEY_CLASSES_ROOT\CLSID key and create a couple of 
additional subkeys: the CLSID of the OLE InProc server refer- 
enced by the Find extension, the command line to be executed 
by FindExt.DLL, which must be stored under the FindCmd key, 
and finally the InprocServer32 key with two values. The first, 
which is the default, contains the path (if appropriate) and file 
name of the FindExt.DLL, which will typically be located in the 
\Windows\System subdirectory. 

The second key, “ThreadingModel,” should be set to “Apart- 
ment” because the FindExt.DLL uses that mechanism andis, in fact, 
thread safe. The threading model applies only to OLE Servers that 
are loading in process. The steps I’ve outlined are a bit tedious, yet 
they must be carried out exactly for this to work properly. To ease 
the procedure, I wrote a small Finder Installation utility that 
automates the whole process (available for download from the 
online services described elsewhere in this article). 


The first step in using this utility is to generate a new CLSID, 
which is equivalent to a GUID (for “Globally Unique ID” in Microsoft 
terminology) or UUID (for “Universally Unique ID,” in DCE/RPC 
terminology). 

VB creates GUIDs for us automatically when we create OLE 
Servers, and the GUIDGen utility included in the Win32 SDK 
can be used to generate them manually. Anyway, | want to 
create a CLSID programmatically so I need to create a GUID 
structure and fill it in by calling the OLE function CoCreateGuid, 
which in turn calls the RPC function UuidCreate. 

The Win32 documentation states that UuidCreate is not 
implemented on Windows 95, but that isn’t true: it can be 
found in RPCRT4.DLL. 

The Win32 header files give this structure for a GUID: 
typedef struct _GUID { // size is 16 

DWORD Datal; 

WORD Data2; 

WORD Data3; 

BYTE Data4[8]; 

} GUID; 


which I translated into this VB code: 


Type tGUID 
Pl As Long 
P2 As Integer 
P3 As Integer 
P4 As Byte 
P5 As Byte 
P6 As Byte 
P7 As Byte 
P8 As Byte 
P9 As Byte 
P10 As Byte 
P11 As Byte 
End Type 


The CoCreateGuid declaration was pretty obvious: 


Declare Function CoCreateGuid Lib _ 
"OLE32.DLL" (guid As tGUID) As Long 


Calling it is dead simple: 


Dim tmp As tGUID 
1Ret = CoCreateGuid(tmp) 


Unfortunately, the GUID you end up with is binary. You need 
a string in this format: “{xxxxxxxx-xXXXX-XXXX-XXXxX- 
XXXXXXXXXXXX}”. The Win32 API does provide a UuidToString 
function located in RPCRT4.DLL and the Win32 SDK header files 
provides this prototype: 


UuidToStringA ( 
IN UUID __RPC_FAR * Uuid, 
OUT unsigned char __RPC_FAR * __RPC_FAR _ 
* StringUuid 
); 


But, it turns out that this function isn’t callable from VB. 
However, another function, StringFromGUID2, gets us on the 
right track using this declaration: 


Declare Function StringFromQUID2 Lib _ 
"OLE32.DLL" (guid As tGUID, IpszString As 
Byte, 1Max As Long) As Long 
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MESSAGE DESCRIPTION 


| ESR SRT RTT AINSI TES FLD ATEN I I ETT FNL LE ILA ORE ST OLED OA 
REG_NOTIFY_CHANGE_NAME Changes to key names that occur in the specified 
key or in the specified key and its subkeys cause 
a change notification. This includes key creations 
and deletions. 
Attribute changes that occur in a key or in a key 
and ifs subkeys cause a change notification. 
Changes to the last write time that occur in a key 
or ina key and its subkeys cause a change 
notification. 
Security-descriptor changes that occur in a key or in 
akey and its subkeys cause a change notification. 


REG_NOTIFY_CHANGE_ATTRIBUTES 
REG_NOTIFY_CHANGE_LAST_SET 


REG_NOTIFY_CHANGE_SECURITY 


TABLE 1 What’s Changed? Registry change notification messages, 
and their descriptions. Be aware that some messages that 
exist on Windows NT aren’t supported by Windows 95. 


Calling this function and putting the result into the Text 
control is a piece of cake: 


Dim bBuff(256) As Byte 
1Ret2 = StringFromGUID2(tmp, bBuff(0), 2568) 
txtGUID = bBuff 


These three lines of codeare doing alot. Thecontents of the bBuff 
byte array are actually a Unicode string. If you examine it in detail, 
you'll see that every element contains the ASCII value of a character 
that you want in the string version. Assigning the contents of the 
buffer to a string (or, in this case, the text property of a Text control) 
converts it correctly because VB4 strings are internally Unicode. 

The second and third steps are to simply fill in the extension 
key name (which is not used), menu text, and complete com- 
mand line that we wish to execute. 

The fourth step is to generate acomplete REGEDIT4 script that 
contains all of the entries in the appropriate format. This is 
straightforward VB string manipulation code (see Listing 1) with 
these caveats: any key value containing a backslash character 
must be doubled and the script must have a blank line at the end 
for the previous line to be registered correctly. The last step is to 
copy this script into a REG file and execute it from the shell. 

Again, because you create your own CLSID, you can have any 
number of Find extensions on a system without worrying about 
colliding with one written and installed by someone else. Be- 
cause the FindExt.DLL is internally calling the new Win32 
ShellExecute function, you can even substitute the executable 
file name with something like this: 


http://www.yahoo.com 


You might associate this with the menu description “On The 
&Internet....” Choosing this automatically brings up the Internet 
Explorer, logs you on to the Internet, and take you to the Yahoo 
finder. Other ideas for Find extensions might include a com- 
pany-wide address book, a shortcut to MSDN, or virtually any- 
thing else that makes sense to you. 


DIFFERENCES BETWEEN NT AND 95 

As developers are all too painfully aware, there are major 
differences between the Windows 95 and Windows NT plat- 
forms. Some of these differences will disappear over time: the 
NT Shell Update Release (SUR) will add the new shell, TAPI 
support, and so on, while some of the most glaring differences, 
like Windows 95’s lack of security, will remain. One of the gray 
areas is support for theWin32 Kernel synchronization objects: 
while support for the file change notifications is supported 
through the FindXXXChangeNotification family of APIs on both 


platforms, support for registry change notifications (through 
RegNotifyChangeKeyValue) is supported only on NT. 

While a full discussion of kernel synchronization objects—such 
as mailslots, processes, threads, mutexes, events, semaphores, file 
handles, file mappings, named pipes—will have to wait until an- 
other time, I'll cover only registry synchronization for now. 

Kernel event objects can exist in either a signaled or not- 
signaled state. Basically, we create an event object, tell the 
system to signal that object when the registry changes, and wait 
for the object to get signaled. Normally this is done synchro- 
nously by suspending the calling thread until the signal occurs. 

Unfortunately, because VB apps can currently use only a 
single thread, this would have the effect of hanging the entire 
app until the change occurs. Freezing an application is consid- 
ered to be sub-optimal from an implementation standpoint 
(users generally don’t like this), so 1 programmed around this 
limitation using a Timer and periodically checking the state of 
the event. While polling is usually a sign of a bad application 
architecture, in this case there’s no other choice. i 

To illustrate this, I created a small testing application that’s 
easy to follow (see Listing 2). The code starts in the 
cmdRegistry_Click subroutine, which creates the event object, 
passes its handle to the system to get signaled when the registry 
changes, and starts the polling timer. The timer calls 
WaitForSingleObject (with a time of 0 milliseconds) and returns 
immediately. 

When the event gets signaled, the timer is disabled and the 
event object is destroyed by closing its handle. This particular 
example looks for changes to key names at the root level of 
HKEY_CLASSES_ROOT and includes subkeys: it’s probably the 
most useful, although you may want to examine the other 
options from the Win32 SDK (see Table 1). 

As a final reminder, since the RegNotifyChangeKeyValue 
function is implemented only on Windows NT, this tester won’t 
do anything on Windows 95. 

Here are some useful tips. First, any long file names stored in 
the registry should be enclosed in quotes, like this: 


shell\open\command = "C:\Program Files\My Accessories\WinWord.Exe" $1 


Alternately, the short file name could be stored so it will work on 
allsystems. An example ofthis is the system-supplied Find utility that 
supplies the “Files or Folders...” and “Computer...” menu items: 


C: \Progra~1\TheMic~1\findstub.d11 


While type and size of data you can store in the registry is 
relatively unlimited, in general you should not store frequently 
accessed data in the registry. Registry access is much slower than 
shared memory and even slower than file access. You should also 
be aware that named values consume less space than keys 
consume. You might also consider packing data together into a 
structure and storing the entire structure as a single binary value. 

If your application is adding more than a couple of kilobytes 
to the registry, consider storing a pointer to that data and 
locating it elsewhere, either as a file or perhaps as atype library. 

Also, while it’s certainly possible, Microsoft strongly encour- 
ages developers not to store binary, executable programs in the 
registry. If you’re still interested in the registry and are looking 
for a place to jump in where you're likely to see familiar stuff, I'll 
leave you with these keys as “suggested reading:” 


HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft \Windows\CurrentVersion\SharedD11s 
HKEY_LOCAL_MACHINE\System\CurrentControlSet\control\SessionManager \KnownDLLs 
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\IniFileMapping 
HKEY_LOCAL_MACHINE\ \ SOFTWARE Microsoft \Windows\CurrentVersion\AppPaths 
HKEY_LOCAL_MACHINE\\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall DI 
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JET REPLIC 


Keep in Sync with 


Jet Replication 


developers, is easy 


when you use VB 
4.0’s Jet engine. 


copies of a database synchronized 
using prior versions of Visual Basic 
or Access, many obstacles impeded your 
progress. In fact, database synchroniza- 
tion required so much coding that few 
developers attempted it. With the sup- 
port for replication and synchronization 
built right into the Jet 3.0 database engine 
used in Visual Basic 4.0 and Access 95, 
replication is finally a reality for many 
developers. 
Replication amounts to making spe- 
cial copies of a regular Access database. 
These copies are enabled in such a way 


| f you wanted to keep two or more 
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that you can easily transfer changes made 
in one copy to each of the other copies. 
Jet replication is composed of three steps: 
replication, synchronization, and conflict 
resolution. 

When you replicate a normal Access 
database, Jet makes many changes to the 
database’s schema, enabling the database 
to exchange updates with other databases. 
When you convert a nonreplicated data- 
base into a replicated database, you end 
up with the design master 
of anew replica set. Arep- 
lica set of one, however, is 
not very useful: there 
would be no one to ex- 
change rules with. Nor- 
mally you create asecond 
member of the replica set 
by replicating the design 
master. Youcan create ad- 
ditional members ofarep- 
lica set by replicating any 
of its existing replicas. 

Two replicas can ex- 
change updates only if 
they are descendants of 
the same design master— 
that is, members of the 
same replica set. The de- 
sign master is a special 
member of a replica set. 
While you can make 
schema changes only in 
the design master, youcan 
make changes to data in 


ever, send changes to the other members 
of the replica set without your interven- 
tion. In fact, unlike networked databases 
in a multiuser file server or client/server 
environment, replicas are not connected 
except when you temporarily connect 
them—two at a time—during a synchro- 
nization exchange. 

When you synchronize two replicas, 
Jet sends updates from one replica to 
another. Jet sends only the updates, a 


Star 


Moderate 


any replica ofa replica set 
(unless you elect to make 
a replica read only). 
When you make up- 
dates to a replica that’s a 
member of a replica set, 
Jet tracks the updates us- 
ing the extra tables and 
fields it added to the data- 
base when you first repli- 
cated it. Jet does not, how- 


44 MARCH 1996 Visual Basic Programmer’s Journal 


FIGURE | Pick Your Topology. LANs can be implemented 
using a variety oftopologies, but each topology presents 
its own setofconsiderations from the standpointofsynchronization. 
Choose a topology according to your priorities: how important is 
latency, network load, and synchronization reliability to you? For 
example, if short latency is essential but network traffic is 
reasonable and the size of the LAN is small, you may want to use 
a fully connected topology. 


process that is much more efficient than 
importing and exporting records between 
two nonreplicated databases. 

Normally, synchronization occurs in 
both directions, but you can elect to syn- 
chronize in only one direction if you wish. 
It’s up to you to control when, and be- 
tween which replicas, synchronization 
occurs. In addition, you must first estab- 
lish a physical connection between the 
two replicas before you can make a syn- 
chronization exchange. 

In between synchronization ex- 
changes, it’s possible that two users may 
modify the same row in different repli- 
cas. When this occurs, Jet flags a conflict 
the next time the replicas are synchro- 
nized. Jet uses a simple algorithm to 
determine which user’s changes are pre- 
served, based on which replica modified 
the record the greatest number of times. 
You can override this automated deci- 
sion by creating custom conflict resolu- 
tion code (unfortunately, space con- 
straints don’t permit me to discuss the 
creation of custom conflict resolution 
code in this article). 


WHEN TO USE IT? 
When you think about it, replication is 
just another way to share data, andcan be 


Topology Ring 
i Latency Moderate 
Load Distribution Even 
Network Traffic Low 


Reliability Good, if direction 
can he reversed in 
the event of a 
node failure 


\ Comments: 

Appropriate for many situations, 

__ especially when you need to evenly 
distribute the load. 


Topology Fully connected 
Latency Low 
Load Distribution Even 
Network Traffic High 
Reliability Good 


Comments: 

Best latency but the most network traffic 
since every replica must exchange with 
every other replica in the replica set. 
Appropriate for applications with a 

small number of nodes where latency 
must be kept to a minimum. 


used in many of the same situations that 
classic file server and client/server sys- 
tems are employed. You may benefit from 
Jet replication in many situations. In gen- 
eral, whenever you need to keep multiple 
copies of the same database synchro- 
nized, Jet replication is a good candidate. 

When designing a system for alocal area 
network, you may have difficulty deciding 
whether to share a single copy of a 
nonreplicated database across aworkgroup 
or to distribute replicated copies of the 
database to each user and regularly syn- 
chronize changes between the replicated 
copies. In most cases the more traditional 
fileserver approach makes more sense 
because of the need for the immediate dis- 
semination of updates to all users. 

Areplicated system has a greater time 
lag between the dissemination of updates. 
This lag period—called the update la- 
tency—may vary from an hour to several 
hours or days, depending on the number 
of users, the volume of updates, the fre- 
quency of conflicts, the synchronization 
topology, and the synchronization sched- 
ule. On the other hand, using replication 
in this scenario might make sense in one 
of these situations: if data is updated 
infrequently, if updates do not usually 
affect other users, if the network is al- 
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Simple fo implement but worst update 
latency. May be appropriate for 
single-master model (data updates 
made only to the design master). 


Topology Tree 
Latency Variable 
Load Distribution Uneven 
Network Traffic Low 


Reliability Depends on where 
the failure occurs 


Comments: 

May be most efficient for applications 
where data updates occur only in 
selected nodes, 


ready overloaded, or if the network is 
often down. 

Another alternative might be to create 
ahybrid system that uses replication and 
file-server sharing, especially when you 
have an overloaded network and can’t 
afford to move to a client/server system. 
You would create multiple workgroups, 
each tied to a workgroup server machine. 
Users within a workgroup would share a 
database residing on the workgroup’s file 
server. The database would be replicated 
across workgroup servers, which would 
be synchronized on a regular schedule. 
This hybrid system would distribute the 
load over multiple servers.Update latency 
would be small within a workgroup, and 
greater between machines in different 
workgroups. 

The speed of the connection between 
two nodes (computers) on a wide-area 
network is slower than that of aLAN. This 
factor usually rules out the use of a file- 
server sharing model on a WANin favor of 
a client/server system. 

With the introduction of replication, 
however, you may wish to consider repli- 
cation instead of a classic client/server 
system when using a WAN. Because syn- 
chronization exchanges transfer only the 
changed records, not whole tables, repli- 
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cation is well suited for WANs. 

In addition to the reasons given for 
using replication on LANs, you may wish 
to consider using replication on a WAN if 
the move to a client/server system is 
considered too expensive. 

Replication is probably not a good 
choice: 


e If users generate many updates, and 
especially if multiple users often update 
the same records, causing alarge number 
of conflicts. 

e If there is a need for the immediate 
dissemination of updates to all users. 

e If data consistency is critical. 


In these situations you’d be better off 
using a classic client/server, transaction- 
oriented approach or the replication ser- 
vices of a server database. (see the 
sidebar, “Contrasting Jet Replication with 
Microsoft SQL Server 6.0 Replication”). 


LOOSELY CONNECTED NETWORKS 

Mobile laptop users, connecting either 
infrequently or over slow modem lines 
to LANs or WANs, do not fit well into 
either the file-server or client/server sys- 
tem, especially when two-way transfer of 
updates is needed. This type of system is 
often ideally suited for Jet replication 
because users can take a replica with 
them when they go on the road, plugging 
back into the corporate network every 
so often to exchange updates with the 
“main” database. 

Two potential stumbling blocks, how- 
ever, affect the use of Jet replication on 
laptops. First, many existing laptops will 
be underpowered for replication— 
laptops running VB must have at least 8 
MB, and laptops running Access 95 must 
have 12 MB of RAM. Because there’s no 
support for the replication of partial 
tables, there’s no easy way to have each 
salesperson’s laptop contain only the 
subset of data pertaining to his or her 
region. 

Fortunately, several possible 
workarounds address this shortcoming. 
One possibility is to have laptop users 
synchronize their data only to the main 
database. Another potential workaround 
would be to have separate “territory” 
tables for each user that could be com- 
bined for analyses using a Union query 
or a routine that created a temporary 
combined table. 

Even if you decide not to use replica- 
tion to share data in a file-server environ- 
ment, you may wish to consider using it 
for maintaining “warm” backups. By rep- 
licating a database and regularly synchro- 
nizing it with another replica (every 15 
minutes or hourly, for example), you'll be 
ready in the event of a disaster that cor- 


rupts or destroys the main database. 

If you’re developing applications us- 
ing Access, where the application is stored 
in the database, you may also wish to 
consider using replication to distribute 
application updates, significantly reduc- 
ing the maintenance burden associated 
with updating an application distributed 
to tens or hundreds of workstations. 

When replicating a database, you 
must decide on a synchronization to- 
pology and schedule for the replica set. 
The topology defines the replicas that 
exchange updates with other replicas, 
and the direction of such exchanges. 
The schedule defines when the ex- 
changes occur and who initiates the 
exchanges. The topology and schedule 
you choose for your replica set affect 
update latency. 


Various topologies might be used on 
a LAN (see Figure 1). The synchroniza- 
tion topology you choose depends on 
the importance of latency, network load, 
and synchronization reliability. If a very 
short latency is of utmost importance, 
network traffic is not a concern, and you 
don’t have many nodes, then you may 
want to use the fully connected topol- 
ogy. Otherwise, the star usually works 
best, with the ring topology another com- 
mon choice. 

All the topologies shown in Figure 1 
are possible on a WAN or a loosely con- 
nected network. You might also use a 
topology that interconnects several 
stars or rings. 


WHAT CHANGES IN REPLICATION? 


When you replicate a database, Jet makes 


Contrasting Jet Replication with 


Microsoft SQL Server 6.0 Replication 


Microsoft has added replication capabilities to Microsoft SQL Server 6.0, as well 
as to Jet 3.0. However, the two products handle replication in substantially 
different ways. 

On the most fundamental level, Jet replication treats the data equally in every 
replica. You can make a change to data anywhere, and it will eventually propagate 
around the entire replica set. In contrast, SQL Server replication employs a “publish 
and subscribe” metaphor. One copy of the database publishes a table, and many 
others may subscribe to it. SQLServer replication is a one-way-only process (multiple 
SQLServer databases may publish parts of the same table using horizontal or vertical 
partitioning, but these multiple publications may not overlap). 

Because SQL Server replication operates on a table rather than a database 
level, it’s easy to replicate tables from one database into a second, otherwise 
dissimilar database. 

SQL Server offers rich scheduling options for maintaining synchronization 
between replicas. Because the server keeps a transaction log, it has the ability to 
synchronize every time a specified number of transactions has taken place in a 
table. Thus, you can ensure that SQL Server replicas differ by no more than a 
maximum number of changed records from the publishing database without 
resorting to frequent, possibly unneeded synchronizations. Text and image 
columns—the SQL Server rough equivalents of memo and OLE fields—cannot 
participate in transaction-based replication. They must be replicated using 
schedule-based replication instead. 

SQL Server does not replicate schema changes to a published table. If you 
need to change the design of a table in a replicated SQL Server database, you 
must delete the old publication, create a new one, and manually synchronize the 
new table into every replica. 

SQL Server replication offers an additional level of flexibility through the use 
of stored procedures to customize replication. A subscribing database can calla 
stored procedure on any replicated insert, delete, or update. This capability 
allows you to design replication schemes in which the data on the subscriber is 
stored differently than it is on the publisher. 

Although SQL Server uses ODBC to move data into subscribing databases, 
neither Jet 3.0 nor SQL Server 6.0 is yet capable of heterogeneous replication. 
Microsoft has announced that SQL Server 6.5 will support replication to Jet and 
other ODBC data sources. Meantime, if you have a client/server database using 
VB or Access for the front end and SQL Server for the back end, you’ll need to use 
the replication capabilities of both products to maintain multiple copies in 
synchronization. For example, you might use Jet replication to ensure that 
geographically diverse users have the same forms and reports while using SQL 
Server replication to publish the data to servers to which those same users 
connect. —Mike Gunderloy 
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a number of changes to the database, 
such as adding fields to each replicated 
table in the database, changing sequen- 
tial AutoNumber fields to random 
AutoNumber fields, adding several sys- 
tem tables to the database, and adding 
properties to database document ob- 
jects. These changes can significantly 
increase the size of your database. 

The tables that replication adds to 
the database are used to track the names 
and locations of replicas and replicated 
tables in the replica set, log synchroniza- 
tion exchanges, track deleted records, 
and log synchronization conflicts and 
errors. All replication system tables are 
read only. Most of the fields in these 
tables are readable, except for some fields 
where the data is stored in binary form 
as OLE objects. 

In addition tothe hidden system tables, 
Jet creates local (non-replicated) conflict 
tables whenever outstanding conflicts oc- 
cur in a database table as a result of a 
synchronization exchange. Jet constructs 
the name of the conflict table by append- 
ing “_Conflict” to the end of the table that 
contains conflicts. For example, the con- 
flict table for tblCustomer would be 
tblCustomer_Conflict. 

When a conflict occurs during syn- 
chronization because a row has been 
updated in both replicas, Jet creates a 
row in the conflict table of the losing 
replica (if this is the first conflict for a 
table, Jet first creates the conflict table) 
and stores in it the losing row. Conflict 
rows appear only in the losing replica. 
The replica with the winning update is 
not notified in any way of the conflict. Jet 
also adds several fields to each repli- 
cated table (see Table 1). All the replica- 
tion fields are read only. 

Jet also alters the behavior of existing 
AutoNumber fields. If a table contains a 
long-integer AutoNumber field with a 
NewValues property setting of Increment, 
Jet changes the property to Random. 
This significantly reduces the chance that 
two replicas will assign the same 
AutoNumber value, because each 
AutoNumber field will be based on a 
randomly selected number between -2 
billion and +2 billion. If this still pro- 
duces too many duplicate values across 
a replica set, you may wish to use an 
AutoNumber field of type Replication ID 
instead. When you use an AutoNumber 
field with a Replication ID field size, Jet 
assigns numbers using a globally unique 
identifier. 

While no system can ever guarantee 
that a number will always be unique, glo- 
bally unique identifier (GUID) numbers 
have been designed with global unique- 
ness in mind. These numbers are also 
sometimes referred to as universally 


unique identifiers, or UUIDs. 

A Jet-generated GUID is a 16-byte 
string made of several parts that, when 
concatenated, have an infinitesimal 
chance of ever generating duplicate val- 
ues. And the “global” in GUID means 
that each GUID will be unique through- 
out the world, regardless of where or 
when it was generated (see Figure 2.) 

GUIDs are used in several places ina 
replicated database to uniquely identify 
many parts of a replicated system, in- 


cluding rows in a replicated table, each 
table in a replicated database, each rep- 
lica in a replica set, each synchroniza- 
tion exchange, each database genera- 
tion, and each schema change. 

Replicating a database adds proper- 
ties to database objects (see Table 2). In 
addition to the properties in Table 2, Jet 
adds several other properties to the 
MSysDb and UserDefined documents of 
the Databases container that only Ac- 
cess uses to manage replication. 


Get All Your Brainwaves 
on the Same Wavelength with 


lient/Server Guidelines” 


LBMS can get all the brainwaves in your 
organization on the same development 
wavelength by channeling that knowledge 
and expertise into common standards and 
guidelines. Client/Server Guidelines is a 
comprehensive tool that allows you to cap- 
ture, maintain and distribute all your appli- 
cations development standards, guidelines 
and policy information in a one-stop, cen- 
tral repository. Using a graphical editor and 
an easy-to-follow hypermedia format, 
changes can be made to the central database 
repository, so developers can add or modify 
guidelines, standards and policies to reflect 
an organization's unique requirements. 
Client/Server Guidelines even comes 
complete with its own industry-proven stan- 
dards to increase productivity and ensure 
consistency; these standards include: GUI 


design for both Windows™ 3.x and Windows 
95, programming, database definition and 
naming and Windows 95 certification. 
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Now, for a limited time, LBMS is offering 
this standards tool for a price of $2495 for 
5 seats. Just give us a call at 800 345 LBMS 
or e-mail us at brains3@Ibms.com 
(please include name, address and 
phone #) to receive more information or 
to order Client/Server Guidelines at this 
great price. 


aa LBIVIS 


CLIENT/SERVER GUIDELINES WAS DEVELOPED BY CCI, AN 
LBMS COMPANY. COPYRIGHT © 1996 BY LBMS, INC. ALL 
OTHER TRADEMARKS ACKNOWLEDGED. 
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ea 
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Jet also adds properties to some TableDef fields. The 
ColGeneration property is added to Memo and OLE Object 
fields. ColGeneration identifies the name of the field used to 
track generations for these large object fields. 


GET REPLICATED 
The first step in employing Jet’s replication services is to 
convert an existing nonreplicated database into a replicated 
design master. 

Using the Jet Data Access Object (DAO), you convert a 
nonreplicated database into a replicated design master by setting 
the Replicable property of the database to “T.” In an odd stroke 
of inconsistency with the rest of VB, Access, and Jet, Microsoft 
has given this and other true/false replication properties a string 
datatype that must be set to the literal String value of “T” or “F.” 

Since the Replicable property of the database will not exist 
until you set it for the first time, you’ll need to add the 
property to the database’s properties collection in order to 
set it. For example, you could use this code to make a new 
design master from a nonreplicated database: 


Sub CreateNewReplicaSet(ByVal strDb As String) 
Dim db As Database 
Dim prp As Property 
Set db = DBEngine.Workspaces(0). OpenDatabase(strDb, _ 
Exclusive:=True) 
Set prp = db.CreateProperty("Replicable", dbText, "T") 
db.Properties.Append prp 
MsgBox txtDb & " has been replicated.", _ 
vbOKOnly + vbInformation, "Create Replica Set" 
End Sub 


Note that I have set the Exclusive parameter of the 
OpenDatabase method to True. To convert a nonreplicated 
database to a replicated design master, you must have the 
database open exclusively. When using Access, you can’t 
convert the currently open database. 


CREATING ADDITIONAL REPLICAS 
Use the CreateReplica method of the database object to 
create additional replicas. Here’s the syntax: 


database.MakeReplica replica_name, _ 


eee nema enema 


Field Datalype Purpose 


Comments 


zac SESE VOI RRA AE O00 ER PEE SES EA IESE SSS ASSIS TE III 


s_Generation Long Integer 


s_GUID AutoNumber, Replication ID Uniquely identifies the row 
across replicas, even if the 
primary key values change. 
s_lineage OLE Object 
Gen_Field Long Integer One Gen field is added for each large object 


(memo or OLE object) user field in the table. 


Tracks changes (generations) fo a row. 


This field tracks the history of changes to the record. 


If value is 0, this represents an added row or a changed row 
that needs to be sent to other replicas during the next 
synchronization exchange. If it is a nonzero value, it 
represents the generation of the replica during 

which this change was made. 


| 
This field will not be added to the table if the 
table contains an existing AutoNumber field 
with a field size of Replication ID. 


| 
| 
| 


This field tracks changes to the large object 
It name takes the format Gen_Field where 
Field is the name of the large object field. 


| 
| 


TABLE Replication Fields Added to Each Table. These fields will appear in the Access UI only when you have elected to show 
system objects. All added replication fields are read only. 
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description [, dbRepMakeReadOnly] If IsMissing(varDesc) _ 
Then varDesc = strReplica2 
db.MakeReplica strReplica2 
varDesc 
MsgBox strReplica2 _ 
& " has been created.", _ 
vbOKOnly + vbInformation, _ 
"Make Replica" 
End Sub 


For example, you could use this sub- 
routine to create a new read/write replica: 


Sub CreateReplica( _ 
ByVal strReplical As String, 
ByVal strReplica2 As String, _ 
Optional ByVal varDesc As Variant) 
Dim db As Database 
Set db = DBEngine.Workspaces(0). 
OpenDatabase(strReplical) 


Jet stores the value of the description 
parameter in the Description field of 


Table (Replicated) 
=a F4C40B8D-44F B-1 1CF-£3F2-444553540000) Long binary data Johnson 
Long binary data Reddick 
Long binary data Stevens 
Long binary data Jones 
Long binary data Smithe_ 
Long binary data_Jenning Roger _ 
Long binary data | Fallon Jane 
_Long binary data Phoner Phil 
Long binary data Jones. Bet 
Long binary data Babitt = Lucy | 
Long binary data | Litwin Paul 
Long binary data Ayala Steve 


__ Alicia Anne | 
Gary 
Kenneth 
Jerry 

__Myma _ 


F4C4088F-44FB-11CF-83F2-444553540001 


14 
1 {FACAOBBE-44F B-11CF-83F2-44455354000 
if 


1 
1 
1 
{ 1 {F4C40890-44F B-1 1 CF-83F2-44455354000 
1 1 {F4C40891-44FB-1 1 CF-B3F2-444553540000} 
ae 1 {F4C40892- 2-44455354000 
1 1 {F4C40893-44FB-11CF-83F2-444553540001 
1 1 {F4C40894-44FB-1 1 CF-83F2-444553540000 
1 1 {F4C40895-44FB-11CF-83F2-444553540000 
1 1 {F4C40896-44FB-1 1 CF-B3F2-444553540000} 
1 1 (F4C40897-44FB-1 1 CF-83F2-444553540000} 
1 1 {F4C40898-44FB-11 CF-83F2-444553540000 
(AutoNumber), (AutoNumber) (AutoNumber) 
Record: at e([ 1 ce trie of 42 i Kil 3 atin - = me 
FIGURE 2. Evidence of Replication. The tblCustomer table shows the replication fields. 
The s_GUID field is a 16-byte string that uniquely identifies each record across 
allreplicas using a sophisticated algorithm that incorporates the system clock, the network 
ID, and several other numbers. ; 


MSysReplicas. You can view and change 
the value using Replication Manager. In 
fact, when you use Replication Manager, 
the description—not the replica name— 
appears in the Replicas drop-down box, 
so you may want to create succinct but 
informative descriptions. 

If you include the optional dbRe 
MakeReadOnly property, the created 
replica will be read only. 

Before you convert a database into a 
replicated design master, prevent docu- 
ment objects from being replicated by 
setting their KeepLocal property to “T.” 
In Access, you can manipulate KeepLocal 
for any document object, including 
tables, queries, forms, reports, macros, 
and code. In VB applications, you need 
to concern yourself only with tables and 
queries, both of which are members of 
the Tables container. By default, the 
KeepLocal property doesn’t exist until 
you create it. 

For example, to prevent Jet from repli- 
cating the tblLocal table in the 
ToBeReplicated.mdb database, use: 


On Error Resume Next 


Dim db As Database 
Dim doc As Document 


| Add-Ins 


ila Code 4.0 urasm 


All the VB gurus agree: You should avoid using 
controls when another method will do. 

Yeah, sure... 

Have you ever tried replacing labels, lines and 
shapes by manually writing the code to print 
directly to the form/picturebox? What a pain! 


But the gurus are right about one thing: Leaving 
labels and other controls on your forms is a big 
mistake if you want snappy performance. Into 
Code converts these controls into native VB 
graphical code. 


MM to C; ode cleans up forms FAST! 


You'll get quick form-loading and you still get 
to do drag n’ drop design changes. Easy to 
use? It’s a VB4 add-in! Just select the con- 
trols you want to convert right on your form 
and click. Builds new form and project files. 
Never touches your original code. 


e Faster form loading 


e Read and write label captions 


e Includes project backup utility 
e Full help system and a manual 


TO ORDER 


CALL 
FAX 


311 RED FOX RUN 


Microsoft Visual Basic {design} 


¢ Convert any label: data-bound or not 


e Create any 3D effect with zero resources 
e Overcomes VB’s control-count limits 
e Even build your own controls - we show you how 


S60 


into Code 4.0 for VB4: $60 


Still using VB3? 
Get both into Code 3.0 & 4.0 for 
$109 


1-800-789-3075 
1-803-875-1748 
INTERNATIONAL 1-803-873-0249 


PROJECTS 


SUMMERVILLE, SC 29485 
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Dim prp As Property 
Const conErrPrpNotFound = 3270 


Set db = DBEngine.Workspaces(0). _ 
OpenDatabase("ToBeReplicated.mdb") 
Set doc = _ 
db.Containers!Tables. _ 
Documents !tblLocal 
doc.Properties!KeepLocal = "T" 
If Err = conErrPrpNotFound Then 
Set prp = _ 
doc.CreateProperty("KeepLocal", _ 
dbText, "T") 
doc.Properties.Append prp 
End If 


Because you cannot be sure if the 
KeepLocal property has already been cre- 


ated, you need to set it in two steps. This 


LISTING 1 A Synch Function. girDbSyncQ synchronizes changes between two members 


routine first attempts to set the value of the 
property. If the property doesn’t exist, er- 
ror 3270 will occur. If this error occurs, the 
codecreates the property and appends it to 
the document’s Properties collection. 

After you have replicated a database, 
the KeepLocal property becomes read 
only. However, you can use the Replicable 
property of objects to make an object 
local or replicated. You can set this prop- 
erty to “T” or “F” (for true or false) in the 
design master, but you can’t set this prop- 
erty to “T” for local objects in nondesign 
master replicas. 

When youchangethe Replicated prop- 
erty ofan object from “T” to “F,” Jet makes 
the object local to the design master and 
deletes it from other replicas during the 
next synchronization. 


) Then _ 


of a replica set. While Jet will synchronize two databases for you, you must 
decide which databases to synchronize, and when. You’re also responsible for making 
sure the two replicas are connected when you want to synchronize them. 


SYNCHRONIZING REPLICAS 

When you make a synchronization ex- 
change between two replicas, Jet cop- 
ies schema changes and data updates 
between the two replicas. The default 
exchange method is two way, which 
means that data updates move in both 
directions. You can also opt for a one- 
way data exchange between two repli- 
cas. Regardless of whether you choose 
two-way or one-way exchanges, Jet al- 
ways propagates schema changes prior 
to data synchronization. 

Synchronizing two databases is simple: 
Jet does all the work. It’s up to you, how- 
ever, to decide when to synchronize and 
with whom. You’re also responsible for 
making sure thetwo replicas are connected 
when you want to synchronize them. 

Initiate synchronization exchanges 
using the Synchronize method of the da- 
tabase object. The Synchronize method 
uses this syntax: 


database.Synchronize DbPathName _ 
[, ExchangeType] 


where DbPathName is the path and name 
of the replica you wish to exchange with, 
and ExchangeType is one of these 
constants: dbRepExportChangesSend, 
dbRepImportChangesReceive, and 
dbRepImpExpChanges. 


The dbRepImpExpChanges constant, 


which tells Jet to send and receive data 
changes between both replicas, is the 
default. A function called glrDbSync(Q) syn- 
chronizes changes between two members 
of a replica set (see Listing 1). 

If you need to synchronize replicas on 
a regular basis and you’ve purchased the 
Access 95 Developer’s Toolkit, you may 
want to use it instead of DAO to schedule 
synchronizations. It’s easier to use, re- 
quires no programming, and maintains 
an excellent history of the exchanges. 

However, creating your own synchro- 


Object Property ~ Description Read/Write Status 
Database DesignMasterID Unique identifier assigned to the design master of a replica set. Read/write 

ReplicalD Unique identifier for replica, Read-only 
All document objects — KeepLocal Set to “T” before the database is first replicated to make an object nonreplicated (local). Read/write before the 

| database has been replicated. 
Replicable Set to “T” after the database is replicated to start replicating an object that was local Read/write 
or fo “F” to stop replicating an object. 

Table document CollsGuid The column in the table that serves as the globally unique identifier (GUID); Read-only 
objects only usually s_GUID, but Jet will use a user-created field of type GUID if the table 


already contains one. 


TABLE 2 Properties Added to a Database. In addition to these properties, the database object has two replication methods: 


MakeReplica and Synchronize. 
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HotMap Guides Users To Your Hot Spots! 


THE ROAD TO MORE POWER! 


If you're programming in Windows using C/C++, Visual Basic 


MORE CONTROL, MORE MILEAGE! 


No other product lets you do what you can do with HotMap and 


or any environment that supports the VBX format, tap into the HotMap PRO: 
power and control offered by HotMap and HotMap PRO. ® Make Hotviap transearent® eAutelabeling® 
HotMap Methods Demo * Define hot spot regions during © * Customize label colors* 
the design or run time ® Support BMP and DIB 
* Choose different visual formats 
acknowledgments * Border coloring* 


° Drag regions 


.. AND MORE! 


Plus, with HotMap you also get TitleSpy for customizing title bars and 
caption bars, MCursor for modifying the mouse cursor, PopHelp for 
creating help windows, ScrollDial* for creating an analog selector 
device, sIInput Spy* for monitoring mouse or keyboard events, and 
HotMap Tools* for defining regions from existing, irregular-shaped 
graphics files. *HotMap PRO features. 


SUCCESS & SATISFACTION: 
HotMap TAKES YOU THERE! 


HotMap 
HotMap PRO 


LPHMW31-IC $169 
LPHMP31-IC $299 


WinWidgets 3.0 


Intelligent Custom Controls for Windows 


WinWidgets is the definitive set of 
controls you need in your toolbox. For 
one low price you get a complete set of 
interface elements including a Grid and 
Spreadsheet, Tabbed Dialog, Spin 
Control, Masked Edit, Picture Button, 
Status Bar, Tool Bar, List Box, Combo Box, and much 
more. The power of WinWidgets will simplify your 


FEATURES: 


* From tab controls to spreadsheets, 
everything you need for interface 
design 


Supports Windows 3.1, Win32s 
and NT with the same API 


development efforts with features such as input validation, 
ODBC database connections, and powerful data handling. 

You can include WinWidgets controls with all popular 
Windows development tools including Visual Basic, Visual C++, and Borland’s Resource 
Workshop. WinWidgets supports both 16- and 32-bit environments to allow you to develop 
tomorrow’s applications today. 


WinWidgets/VBX LPWWV31-IC $199 
WinWidgets++ LPWWC31-IC $299 
WinWidgets/32 LPWW323-IC $399 
WinWidgets Source Edition LPWWPR3-IC $699 
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data control 


Aesthetic 3-D look 
Easily customized 


Works with AppStudio, Resource 
Workshop, the NT Dialog Editor 
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the MFC 


CALL & ORDER TODAY! 
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nization schedule using DAO has some 
advantages. For example: 

It allows you to deliver a VB-only solu- 
tion. You don’t have to install and use 
Replication Manager (see the accompa- 


eee eri 


nying sidebar, “Tools for Managing Jet 
Replication” for more information on 
managing replicated databases). 

e You have more flexibility in scheduling. 
Replication Manager uses a day-of-week 


& Determine Yolume of Updates for a Replica 


lel Es 


Replica Browse 


DAVBPJ\Replication] \Ch13B.mdb 


Click the Count Updates button ta count up the 
number of updated or new recards in all 


replicated tables in this database. 


Number of [2 Elec | 
Updates Eee 
FIGURE 3 Count the Updates. The UpdateVolume form counts the number of updated 

records since the last synchronization exchange. This number could be used to 
initiate a synchronization exchange only after so many updates were made to a replica. 


Tools for Managing Jet Replication 


VB is great for creating applications that manipulate replicated databases, but 
you may find it easier to use Access 95 or Replication Manager to set up and 
manage replicas. You can use the Access 95 menus to easily replicate and 
synchronize databases. You can also use Access to resolve synchronization 
conflicts and transfer the design master status from one replica to another. The 
replication-related commandsare located under Tools selection of the Replication 
submenu. 

The Access 95 Developer’s Toolkit includes a utility called Replication 
Manager (see Figure A). Like Access, you can use Replication Manager to 
replicate and synchronize replicas and transfer the design master status from 
one replica to another. In addition, Replication Manager includes a facility for 
creating a regular synchronization schedule that a companion program called 
the Transporter uses to perform unattended synchronization exchanges. 
Replication Manager also includes tools for reviewing synchronization logs and 
for easing the management of remote replicas. —P. L. 


. Microsoft Replication Manager - Chi3Ex1 
File View Tools Help 


Folders: |D:\BkSybex2\PAUL\Ch13 | Replicas: | Design Master of Ch13Ex1 | 
HS] Sl) Sex| .lts./| QlQl re 


WOMBAT 
(2 Managed Replicas) 


Managed Replicas | General | 
Members of 'Ch13Ex1’ at this Transporter: 


Replica Description 
Replica 3 of Ch13Ex1 (Remote? 


For Help, press F1 
FIGURE A Remote Management. Replication Manager is used to manage a replica 
set across a WAN. The local machine, Wombat is exchanging updates with 
a replica on the remote machine, Zebra. 
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schedule and allows synchronization only 
every 15 minutes. 

e You can create a hybrid synchroniza- 
tion system based on both aregular timed 
schedule and update volume. 


If you decide to implement a synchro- 
nization system using DAO, you'll need to 
decide how the process will be driven. 
Most likely you’ll employ a hidden form 
that’s automatically loaded when the ap- 
plication is started with code attached to 
the form’s Timer event. 

This form would likely follow a sched- 
ule that was stored in a table in the data- 
base. But where will this hidden form and 
table reside? Should it be part of the 
normal application that runs on each desk- 
top, or should it perhaps run only on 
selected desktops? 

The answer depends on your chosen 
synchronization topology. In any case, 
you don’t want all replicas attempting 
to synchronize with each other at the 
same time. 

One solution might beto keep this part 
of the application separate from the rest 
of your application. This application could 
run Off the file server or the database 
administrator’s desktop. 

You may wish to implement a syn- 
chronization system based on update 
volume rather than (or in addition to) a 
regular schedule. You can determine the 
update volume by counting the number 
of records in each replicated table in the 
database where the s_Generation field 
equals 0. This number represents the 
number of records that have been up- 
dated or added since the last synchroni- 
zation exchange. 

I've created a sample form, 
UpdateVolume, that demonstrates this 
technique (see Figure 3). Open this form, 
select a replica, and click the Count Up- 
dates button. After a brief delay, the 
number of updated records in the repli- 
cated tables in the database is displayed 
in a text box on the form. 

This example doesn’t do anything 
with the value, but once you’ve deter- 
mined the number of updated records, 
you can easily decide whether it’s time 
to synchronize. 

Replication is an exciting new addi- 
tion to the Jet engine. Jet 3.0’s support 
for replication increases your available 
options for sharing data. Now it’s your 
turn to dig in and put Jet replication to 
work. 

The code in this article is included in 
a sample VB project called REP1.VBP 
that you can download from the VBPJ 
Developer’s Exchange on CompuServe 
(GO WINDX), The Microsoft Network 
(GO WINDX) and the World Wide Web 
(http://www.windx.com). &! 
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chair when the phone rang. “Hello?” 

I said in my this-had-better-be-a- 
good-reason-to-bug-me-on-Saturday 
voice. I figured MCI was calling me with 
another pitch but it turned out to be Fred 
in trouble again. Fred, one of my 
daughter’s soccer team parents, thinks 
that because | work at Microsoft I must 
be a computer guru. I should have told 
him I was an IRS agent. 

Fred’s office had just installed SQL 
Server, but a few problems still loomed 
over a Monday morning deadline to go 
online. I said, “You know this is Saturday, 
right?” He knew. 

The database had been built and the 
data loaded, but the front end had be- 
come troublesome. Fred had read my 
book, andI assumed he had taken some of 
my advice. 

“So, your VBSQL applications aren’t 
working?” I queried. 

“Actually, we decided to use the new 


| was just nodding off in my big blue 
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Remote Data Objects instead.” I provided 
a pregnant pause. Finally he broke the 
silence. “Ah...does RDO have a problem 
we should know about? Should we have 
used VBSQL instead? Or maybe Jet DAO? 
Aconsultant I know had argued for that.” 

“No, no.” I replied. “I’m just surprised 
you used RDO. It’s fairly new and not 
many people have tried it yet. VBSQL 
would have been the conventional choice. 
However, you would have had a tougher 
time coding it. As for DAO, certainly a lot 
of people still use that, especially if they 
have a background in dBASE. But you 
chose the right technology for the long 
run. RDO suits the size of the system 
you’re working with, especially since you 
depend so heavily on secure stored pro- 
cedures. On the other hand, this call tells 
me that being the pioneers caught you a 
few arrows.” 

“You got that,” Fred said. “We set up 
the new server using stored procedures 
all right, but we haven’t been able to get 
them working properly. Could you come 
over and take a look?” 

“Tll be there in twenty minutes.” My 
spouse shook her head in resignation. 
She knew I'd be gone for most of the 
weekend. I pushed the stopwatch button 
on my watch. Fred was now on the clock, 
and at my double-time weekend rate. 


WRESTLING WITH THE RESULT SET 
It turned out that Fred had the problems 
I’ve come to expect from sites that mi- 
grate from ISAM-based systems to true 
relational client/server. In many cases, 
these sites must convert older applica- 
tions that perform many of the tasks now 
done entirely by the intelligent back end. 
Examples include maintaining indexes, 
finding data subsets, and performing bulk 
operations on those subsets. 

In systems based on ISAM (IBM’s 
nonrelational, hardware-dependent In- 
dexed Sequential Access Method which 


permits both direct and sequential ac- 
cess to file records), apps work directly 
with the base tables. Such apps often 
handle system maintenance tasks such 
as compression or repair routines. 

Relational systems rarely permit rou- 
tine access to the base tables, much less 
let you add indexes or new tables on the 
fly. Youcan create applications that work 
directly with the indexes and tables, but 
in most serious systems—especially 
large enterprise installations—their ad- 
ministrators prevent access to base 
tables. Instead they create SQL views or 
stored procedures that extract data in 
carefully orchestrated ways. Administra- 
tors appreciate this, along with the abil- 
ity to assign permissions to procedures 
and views that cannot be assigned to the 
base tables. 

Fred’s team had done a pretty good 
job of setting up the database. They used 
the Access Upsizing Wizard for the initial 
conversion, and hired a consultant to 
build a number of intelligent stored 
procedures to return and update the data. 
The consultant completed the task and 
then went off to Australia. 

The errant consultant’s procedures 
asked a series of questions that returned 
a varying number of result sets based on 
the answers. Fred’s group was having 
trouble with the complexity of the result 
sets. For example, the front-end applica- 
tion queries the database to find available 
hotel rooms that match a set of criteria. 
Since the hotel rooms vary so much in 
type and suitability, the agent using the 
application was permitted to walkthrough 
a decision tree to permit faster selection 
of the room best matching the requested 
features. The result sets provide answers 
to the questions: 


e What hotels in the area chosen have 
available rooms? Once a hotel is chosen... 
e How many rooms does the chosen ho- 
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FIGURE Keys to the Kingdom. Windows 95’s Regkdit program lets you display the registry keys used in the application. These R 
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were created manually at first and filled in with code from the application. The Get Setting function pulls out the information 
based on app name, section and key, with a single function for each entry. This process uses less than half the code it would have taken 
to use the Windows API registry functions, and eliminates the risk of blowing up your app by overlaying memory when the values come 


back from your AFI calls. 


tel have for the date given? If more than 
zero, then... 

e How many of these available rooms are 
the right type, with the right number of 
beds? 

e Does the cost of these rooms fall within 
the requested price range? 


If the stored procedure discovers a 
“no” answer to any of these questions, it 
doesn’t go to the next step. This design 
separated each question into a separate 
procedure. This way, given appropriate 
parameters, the base procedure can call 
subsequent procedures down the line. In 
other situations, lower-level questions 
can be asked by calling the subordinate 
queries directly from the app. And to 
Fred’s consternation, he discovered that 
each SQL operation returns a result set, 
so one procedure might return two or 
more result sets. 

In both VBSQL and RDO you can eas- 


ily capture the returned arguments sent 
back by each step. In DAO, on the other 
hand, you must execute a make-table 
query to build a permanent Jet table that 
must be dealt with once the operation is 
done with the result set. DAO users must 
also deal with name collisions and other 
multiuser concerns that RDO handles 
automatically. 

Note that if the procedure performed 
action queries, and you need to capture 
the rows affected by the Update state- 
ments, ODBC does not support this func- 
tionality for multiple result set queries. 

Don’t be surprised if your own stored 
procedure implementation rivals the con- 
volution of Fred’s hotel query plan. Con- 
sider this technique to examine result set 
return values. Basically, a query—especially 
one using stored procedures—can return: 


e A “return status” set by passing back an 
INT value from the procedure. 


e Zero or more sets of data rows—one for 
each select statement that returns rows. 
e Zero or more output parameters. 

e A “rows affected” value for non-select 
queries like update, insert, or delete 
statements. 


All but the rows-affected value can be 
retrieved from procedures that return 
one or several sets of results (see Listing 
1). The code in Listing 1 comprises a test 
procedure that makes use of most of 
these return arguments. The procedure 
accepts the name ofa city, and finds any 
hotels with available rooms. It also re- 
turns the range of prices for those rooms 
and the total number of vacant rooms in 
the city’s hotels. Try to ignore the way 
Fred wrote the select statement and fo- 
cus on the mechanism used to pass argu- 
ments to and from the procedure. The 
procedure accepts an input parameter 
and returns two output parameters as 
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well as a row set. 

Next you need techniques to call stored procedures. RDO lets 
you call stored procedures in a variety of ways, but if you want to 
have RDO help you pass parameters back and forth, you really 
should use the rdoParameters collection associated with the 
rdoPreparedStatement object. This also permits you to set a 
number of important options like MaxRows and RowsetSize, and 
access the RowsAffected property after it executes. But before 
exploring these nuances, look at your options. In each case, a 
connection (Cn) has been established to the back-end server: 


Dim Cn as rdoConnection 

Set Cn = rdoEnvironments(0)._ 
OpenConnection(dsname:=" 
prompt:=rdDriverNoPrompt, 
connect :="UID=; PWD=; _ 
Database=Workdb;"_ 
Driver={SQL Server};_ 
Server=SeQueL;" ) 


This hard-codes the driver and server name into the connect 
string, so you don’t have to install and manage a data source 
name (DSN) on every workstation that runs the app. As an 
alternative, I also showed Fred how to capture registered DSNs 
from the registry and choose one from the list. 

A better approach, however, saves the server name in the 
registry. Because the VB4 help example for registry functions is 
dysfunctional, I had to give him a nudge in the right direction. In 
his case we set up the registry when the application was 
installed and used this setting thereafter. Establishing aregistry 
setting was straightforward: 


" Place the settings in the registry. 
SaveSetting "RDO _ 


Sample App", "Settings", "Server Name", "SeQueL" 
SaveSetting “RDO _ 
Sample App", "Settings", "Driver", "{SQL Server}" 


Irun this code when I’m first setting up the program. Later 
in the initialization routine, we simply read in the registry 
settings. Note these are all stored in a special registry loca- 
tion (see Figure 1). Fred wanted to know if he could use 
another registry path. He also wanted to know why he had to 
use the registry instead of an INI file. I told him that his path 
must use \HKEY_CURRENT_USER\Software\VBasic and VBA 
program settings. “Of course,” I added, “you could use the 
Windows API settings.” Fred looked like my four-year-old 
when she finds brussels sprouts heaped on her plate. He 
didn’t exactly enjoy using the APIs directly. 

The registry is the new de facto-standard location for 
storing program settings such as these. By doing so, Win- 
dows 95 and Windows NT can help manage the settings as 
part of the registry security mechanism. Other applications 
can also locate these settings more easily; they don’t get 
confused about what INI file is used or where it’s saved. And 
users have a harder time accidentally erasing or munging the 
registry. This happens all the time when you use INI files. 

To get the settings out of the registry, you pull up the 
server name and ODBC driver to use from their correspond- 
ing registry slots: 


Dim ServerName As Variant 
Dim Driver As Variant 


ServerName = GetSetting(appname:="RDO 
Sample App", section:="Settings", 
Name", Default:="Unknown") 


keyoGapver = 


REMOTE DATA OBJECTS — 


| 
| 


| 
CREATE PROCEDURE FindHotelInCity 


@CityWanted oe 
@MaxPrice Money OUTPUT, 
@MinPrice Money OUTPUT 


| 
AS | 
declare @cnt int i 
Select Hotel, Count(*) “avai lable Rooms" 
from Hotels H, Rooms R 
Where H.ID = R.HotelID and 
City = @CityWanted and — 
R.Vacant = 0 | 
group by Name | 
| 


Select @cnt 

from Rooms R 

where HotelID in(select ID from hotels _ 
where City = Gol emantedye 

and R.Vacant = 0 


= Count(*) | 
| 


Select @MaxPrice = Max(Price) 
from Hotels H, Rooms R © 
Where H.ID = R.HotelID and 
City = @CityWanted and 
R.Vacant = 0 | 


, @MinPrice = Min(Price). 


Return @cnt 


LISTING 1 Get the Best Rate. A Transact SQL stored procedure, 
FindHotelinCity, returns the highest- and lowest-priced 


room at any hotel in an indicated city. The procedure accepts a 
single input parameter and returns two output parameters. It also 
returns a set of rows for each hotel in the desired city indicating the 
hotel and a count of its rooms. 


Driver = GetSetting(appname:="RDO _ 
Sample App", section:="Settings", 
Default:="{SQL Server}") 


Key:="Driver", _ 
Then you stick the settings into the RDO OpenConnection 
method to gain access to the specific server and driver: 


Dim Cn as rdoConnection 
Set Cn = rdoEnvironments(0).OpenConnection _ 


(dsname:="", prompt:=rdDriverNoPrompt, _ 
connect:="Server="_& ServerName & ";Driver=" & _ 
Driver & ";" & "UID=;PWD=;Database=Workdb;" ) 


Both methods assume that the SQL Server has domain-man- 
aged (integrated) security enabled, and that as a result users don’t 
need to provide a password or user name. As long as they get 
access to the workstation and can log into the network domain 
controller, they can gain access to SQLServer. The Windows logon 
interface captures both the UID and PWD values and passes the UID 
along to the SQLServer security manager, as long as youcodethem 
according to the method I showed to Fred. 

Fred wanted to know if he had to use the new coding syntax 
that kept appearing in my examples. | told him that I like the new 
named-argument syntax because I don’t have to put in commas 
as placeholders for missing arguments. But you can still use the 
old comma-delimited syntax if you are into commas. 

Once Fred’s application was connected, he needed to call the 
procedure we had set up. Fred had been using ISQL to manage 
these procedures, but found it a pain to have to remember to 
drop the procedure each time. 

“Aren’t you using SQL Enterprise Manager?” I asked. 

“Sure, on the server. But that system is across town in the 
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central IS facility.” 

I asked, “Why don’t you install it here 
on your Windows 95 system?” 

“You can?” 

We spent the next few minutes run- 
ning Win95’s SQL Server setup utility. 
Before long we had registered into his 
remote server and were doing mainte- 
nance on his stored procedures. By keep- 
ing one window open for SQL Enterprise 
Manager we could keep an eye on the 
connections being used and tune the pro- 
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cedures while working on the new Visual 
Basic app simultaneously. 

Then we created an rdoPrepared-State- 
ment to execute the procedure and manage 
the various input and output parameters. 

“Where are the input arguments for 
the procedure coming from?” | asked. 
“The stuff going into the procedure—are 
you going to get them from a drop-down 
list box or from a text-box control? 

“They're coming from a text box for 
now,” Fred said. “We might use a list box 
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later. The old application filled a list box 
from data we read in from a separate 
initialization file, but we don’t plan to use 
that file anymore. Now we put the data in 
anew database table.” 

Isuggested we use RDO to set up anew 
database table, and bind one of the new 
DBList or DBCombo controls to the data- 
base table. But Fred declined the offer. “I 
think! can handle that later,” he said. “For 
now, let’s just use the text boxes.” 


CAREFUL SYNTAX 

I showed Fred how to code the 
CreatePreparedStatement function. He 
tried to do it earlier, but he received 
object reference errors due to faulty SQL 
syntax. When RDO asked the ODBC driv- 
ers to execute SQLPrepare, he’d get an 
rdoPreparedStatement, but no 
rdoParameters collection. I showed him 
the right syntax for his procedure. As we 
worked through the coding’ for 
CreatePreparedStatement we failed not 
on the create statement itself, but on the 
first reference to the rdoParameters col- 
lection. If the process of checking the 
syntax of the SQL argument fails, few 
outward signs will tip you off. 

“Shouldn’t the rdoErrors collection 
have an entry to show that the syntax was 
wrong?” Fred wondered. 

“You’d think so, but no, bad syntax is 
not caught at the Visual Basic level, so 
there are no entries we can test for.” | 
answered. “You just have to be careful. 
Look here. We left out the ‘call’ keyword. 
That’s the problem.” 

To show Fred I had not made up this 
answer, I added several lines of code to 
examine the rdoErrors collection. We did 
find the informational messages returned 
by the driver to indicate that SQL Server 
had changed databases and set the de- 
fault language: 


Sub ShowErrors() 

Dim er As rdoError 

For Each er In rdoErrors 
Debug.Print er.Description 

Next 

End Sub 


This code dumped three errors that 
were really just informational messages. 

We made sure to clear the rdoErrors 
collection after having opened the con- 
nection, to see if errors popped up. We 
refocused on CreatePreparedStatement 
again. 

“Why did you add the database name 
to the SQL statement?” Fred wanted to 
know. 

“Without it, the ODBC driver can’t al- 
ways find the procedure.” 

“Doesn’t it just send down the proce- 
dure to be executed?” 


“Not really. The ODBC driver and RDO 
must determine the data type of each 
parameter sent and received. This way it 
can bind to the variables and properly 
format subsequent calls that reference 
the returned arguments. To do this, the 
ODBC driver queries the SQL Server for 
specific information about each param- 
eter specified. Without explicit address- 
ing, especially for those procedures in 
the master database, the driver can’t 
locate the procedure. To be safe, | al- 
ways add the full path to the procedure. 
If you want to see details about how this 
is done, check out the ODBC logs.” 

But he wanted to get the form-load 
procedure written, so we did it (see 
Listing 2). 

Fred didn’t notice that I had selected 
the ODBC cursor driver. This simplifies 
the process of handling multiple result- 
set stored procedures. While you can 
execute multiple result-set procedures 
(procedures with more than one select 
statement) using the server-side cursor 
library, you must create a single-row, 
forward-only, read-only cursor. 

We can use rdoPreparedStatement 
later in the application as well. The next 
step involves coding the command pro- 
cedure that runs the query and returns 
the rows. We just have to set the param- 
eter and use either the Refresh method 
to rebuild the existing rdoResultset or 
the OpenResultset method to create a 
new rdoResultset. 

“Can’t we just create a new 
rdoResultset each time?” Fred asked? 

“Sure. But RDO, unlike DAO, keeps 
the old rdoResultset objects when you 
don’t explicitly close them. To avoid fill- 
ing up memory, you must remember to 
close them down when you’re done. But 
your design doesn’t let us know if we’re 
done until we need to create another. So 
we need to tell VB to close the old 
rdoResultset before we create another: 


While rdoResultsets.Count 
rdoResultsets(0).Close 
Wend 


This routine closes down all 
rdoResultset objects, so you might not 
want to use it as is. Since the rdoResultset 
rs is a global variable, you could just 
say: 


rs.Close 


REFRESH SPEEDS UP SQL SERVER 

However, one of the faster strategies that 
leverages the existing rdoResultset uses 
the Refresh method: you simply change 
therdoPreparedStatement parameter and 
use the Refresh method to re-run the 
query, which not only makes program- 


ming easier, but itimproves performance. 
This way SQL Server does not have to 
rebuild and recompile the procedure each 
time it runs. That’s the whole idea behind 
anrdoPrepared-Statement. It builds acus- 
tom stored procedure for you, designed 
to accept parameters. 

“OK, let’s use the Refresh method.” 
Fred was caught up in the process now. 

“Fine. But if we do that, we need to 
add a line or two to create the first 
rdoResultset based on the query.” 


We needed to add code that either 
created the first rdoResultset or executed 
the Refresh method. The rdoResultset is 
created using rdOpenStatic (like a DAO 
snapshot) and the rdConcurReadOnly 
(which makes the result set read-only) to 
improve performance. 

Generally, don’t ask for features such 
as updatability if you don’t need them. 
As a matter of fact, you could probably 
use rdOpenForwardOnly because you 
don’t expect to move around in the cur- 
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it lets you write better Visual Basic’ code in less time. 


VB COMPRESS PROFESSIONAL 3.0 


Compress Help 


Global Constants 
Global Variables 
Global Type Dets 


Global API Procs 
Module Constants 
Module Variables 
Module Procs 
Form Variables 
Form Procs 


19.736 
16.267 284 

3,469 
18% 13% 


VB Compress Pro—the powerful analysis and optimization tool that cleans 
up your code in minutes, not weeks. Click ANALYZE to get complete 
project metrics and a wealth of other essential details. Click OPTIMIZE to 
get a new copy of source code without a single unnecessary byte. No 
overhead from standard headers or libraries. No duplicate or obsolete code 


that crept in during development. 


Every feature of VB Compress Pro 4.0 is new or improved. There’s a 
smarter, faster parsing engine and a snappy new interface. Reporting options 
include cross referencing, data type and scope information. Optimization 
includes server mode, interactive mode for decision-making on the fly, and 


batch mode for non-stop processing of 
multiple projects. 


VB Compress Pro 4.0 works with all of 


Visual Basic 4.0’s new features, from 


classes to conditional compilation, in 16 and 


32 bits. And it now offers enhanced 
performance with previous versions of 
Visual Basic. 


See for yourself why we win awards. 
Call toll-free and order today. $100 + $6 
s&h, $10 overnight. Satisfaction guaranteed! 


hippleWare. 


Cope Without Compromise 


20 Cedar Street 
Charlestown MA 02129 
Orders: (800) 241-8727 
Phone: (617) 242-2511 
Fax: (617) 241-8496 
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Private Sub Form_Load() 


Set en = rdoEnvironments(0) 
en.CursorDriver = rdUseOdbc 


ServerName = GetSetting(appname:="RDO Sample App", _ 
section:="Settings", _ 
Key:="Server Name", Default:="Unknown") 
Driver = GetSetting(appname:="RDO Sample App", _ 
section:="Settings", _ 
Key:="Driver", Default:="{SQL Server}") 
' Next, we stick them into the RDO OpenConnection method 
" to gain access to the specific server and driver: 
Connect = "Server=" & ServerName & ";Driver="__ 
& Driver & ";" & "UID=; PWD=;Database=Workdb;" 
Debug.Print Connect 
Set Cn = rdoEnvironments(0).OpenConnection(dsname:= 
Prompt:=rdDriverNoPrompt, Connect:=Connect) 


we 
’ 


rdoErrors.Clear_ 

SQL = "{ ? = call Workdb..FindHotelInCity (?,?,?)};" 
Set ps = Cn.CreatePreparedStatement("", SQL) 

If rdoErrors.Count > 0 Then ShowErrors 


If ps.rdoParameters.Count > 0 Then 
ps(0).Direction = rdParamReturnValue 

" ps(1) does not have to be set. 

" The default direction is rdParamInput 
ps(2).Direction = rdParamOutput 
ps(3).Direction = rdParamOutput 


Else 
MsgBox "Could not create _ 
prepared statement query. Call Fred at home” 
End If 


End Sub 


LISTING Prepare a Statement. Sub Form_Load gathers the 
current server name and driver from the registry. 


Using these parameters, the procedure then opens a connection 
and tries to build an rdoPreparedStatement to be used later. 


sor once it is built: we move forward as we fill a list-box 
control with the row. But I'll just leave it as static for now. We 
then extracted the contents of the first and second output 
parameters and the return value, which were placed in text- 
box controls on the form (see Listing 3). 

The ShowRows subroutine simply dumps the rows we found to 
a list box. RDO is coded so much like DAO, this was easy: 


Sub ShowRows() 
Listl.Clear 


While Not rs.EOF 
Listl.AddItem rs(0) 
rs.MoveNext 

Wend 


End Sub 


“But doesn’t the procedure return more than one set of 
results?” Fred asked. 

“Sure, but output parameters handled all the results of the 
internal procedures,” I answered. “Look at every select state- 
ment in the stored procedure. They assign values to stored 
procedures variables like @MaxPrice and @cnt; they don’t 


Private Sub ShowHotels_Click() 
ps(1) = Text1l.Text 
"While rdoResultsets.Count 
"rdoResultsets(0).Close 
"Wend 
If rs Is Nothing Then 

Set rs = ps.OpenResultset(rdOpenStatic, _ 
rdConcurReadOnly) 
Else 

rs.Requery 
End If 
Text2.Text = ps(2) 
Text3.Text = ps(3) 
Text4.Text = ps(0) 
ShowRows 


" Output parameter 1 
" Output parameter 2 
" Return Value 


LISTING 3 Reservation, Please? The Sub ShowHotels procedure 
opens an rdoResultset based on the chosen hotel. Once 

the result set has been created, subsequent executions simply 
rebuild it using the rdoPreparedStatement and the Refresh method. 


return rows. If youruna select statement like this from ISQLor 
SQL Enterprise Manager, you don’t get the results of the query 
at all. You just get the error message, ‘number of rows af- 
fected,’ because the results are stored internally and not 
returned as a row. 

“If you add a select statement that returns a value and makes 
sure there is acolumn name, you'd beable to capture the results 
as the second or “nth” result set. Suppose you add a select 
statement to the procedure: 


Select ID,Name,Zip, Substring(City,1,2) CityCode _ 
From Hotels Where City = @CityWanted 


Note that when you issue a select statement that includes a 
function (like Min, Max, or Substring), SQLServer doesn’t assign 
a column name, making it hard for the interface (like the ODBC 
driver) to recognize and manage the column. To help, I always 
label the columns using the TSQL aliasing syntax. 

“Now, we can adapt the code to deal with this extra result set 
if you want to,” I said. I'll set up a new stored procedure that 
returns another result set using our little select statement, with 
a bit extra: 


r = rs.MoreResults 
" Get the next set of results. 
If r Then 
List2.Clear 
Do Until rs. EOF 
List2.AddItem rs(0) & ":" & rs(1) &" - 
rs.MoveNext 
Loop 
End If 


" & rs(2) 


The first line asks the RDO interface if there are more result 
sets to deal with. If MoreResults returns True, the code pulls 
down the result rows and puts them into a list box. When you 
move to the next result set, you lose access to the previous 
result set. It does not remain in the rdoResultsets collection for 
later examination. 

By the time I got home, Fred had most of his app put back 
together and one of our cats had burrowed into a throw cushion 
on my blue chair. I lifted her, pillow and all, and put her on the 
floor at my feet. I had just settled back into the blue chair when 
the phone rang. I didn’t answer it. 

My daughter called down from upstairs. “Dad! It’s some guy 
from MCI....” X! 
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Fuel? 


Create Dynamic, Graphical Database Interfaces 
That Iell The Story In A Flash. 
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databases. Give yourself a competitive edge with RSTools’, : aes 
eae ne Datasouce OO @ 
our unique line of graphical OLE Custom Controls that let YoU stools graphically displays and manip- 
turn any data into a picture that communicates the story in “lates your database information. 
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Starting From $199.00 ROCKWELL 
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Thunk Before You 
Port 


BY STEVE JACKSON 


| techniques for 
calling 16-bit DLLs 
from 32-bit Win95 
applications save 
time and money. 


custom development to Windows 95 

and VB4, an important technical trade- 
off has been overlooked by many pro- 
grammers and the press. The move to a 
flat memory model in Windows 95 comes 
at a price: a 32-bit VB program cannot call 
a 16-bit DLL. 

Consequently, developers face the 
daunting task of rewriting 16-bit DLLs as 32- 
bit DLLs. If you’re on tight project deadlines 
like I am, you should seriously consider 
thunking as atechnique for saving time and 
salvaging the hard work you've put into 16- 
bit DLLs. What’s more, if you have third- 
party 16-bit DLLs without the source code, 
you can’t rewrite them. Your options are to 
purchase 32-bit upgrades, or use the 
thunking techniques I'll describe to tap 16- 
bit third-party DLLs from 32-bit Win95 apps. 

Here’s the crux of the 16-/32-bit DLL 
dilemma. The way Windows 95 loads a DLL 
and passes function arguments is quite 
different in 16-bit and 32-bit modes. The 32- 
bit code uses data pointer types, stacks, 
CPU register settings, and function-calling 


| n the well-publicized push to move 


Steve Jackson works at a Southern Califor- 
nia aerospace company, developing net- 
work-based applications in VB and C. He is 
a section leader on the VBPJ CompuServe 
forum and can be reached at 72040, 1640. 
Code for this article is available from the 
Magazine Library of the VBPJ Forum. 


conventions that differ from 16-bit code. 

Porting a 16-bit DLL to 32-bit requires 
code changes to function declarations, 
pointer definitions, and memory-handling 
routines that will stretch your project dead- 
lines if you attempt a rewrite. If you try to 
call your 16-bit DLL from a 32-bit VB pro- 
gram, you'll quickly find that VB (or any 32- 
bit Windows program) fails with an “Error 
loading DLL” message. 

However, you can salvage the hard work 
you've put into 16-bit DLLs by calling them 
from your 32-bit applications using a Win- 
dows 95 technique called flat thunking. 
Thunking allows your 32-bit VB app to call 
a 32-bit DLL which in turn calls your 16-bit 
DLL through the thunking layer—a kind of 
hyperspace leap where code reaches 
through a 32-bit thunking layer to grab 16- 
bit DLL functions. 

I'll show you how to create a simple 16- 
bit DLL, and then cre- 


special fixes to the DLL loading code to 
create a 16-bit stack, switch stacks on thefly, 
and translate return values. 

Unfortunately, Windows NT uses a dif- 
ferent thunking model called generic 
thunking that allows 16-bit code to call 32- 
bit code, but generic thunking does not 
allow 32-bit code to call 16-bit code. Ge- 
neric thunking loads a 32-bit DLL into the 
Virtual DOS Machine (VDM) whereNT runs 
16-bit applications. Flat thunking is not 
supported in Windows NT—it works only 
in Windows 95. 

For information on the various thunk 
permutations, read the Knowledge Base ar- 
ticleQ125710onthe MSDN Level 1 CD, “Types 
of Thunking Available in Win32 Platforms.” 
Alsoread the Microsoft MSDNarticleQ125715 
on the MSDN Starter Kit that comes with 
VB4, “Calling 16-bit Code from Win32-based 
Apps in Windows 95.” While it’s a good 


ate a 32-bit DLL that 
calls the 16-bit func- 
tions using thunking. 
Pllexplainallthecode 
you need, saving you 
days’ or weeks’ worth 
of searching for the 
right tools. Along the 
way I'll correct a few 
errors and omissions 
in the Microsoft 
instructions.The 
project requires C 
compilers, assembly 
language, several 
utilities, and of 
course VB4. 

Flat thunking con- 
verts flat 32-bit param- 
eter memory ad- 
dresses of Windows95 


//MYDLL16.C 
#include <windows.h> 
// The standard 16 bit DLL opening 
int FAR PASCAL LibMain (HANDLE hInstance, WORD 
wDataSeg, WORD wHeapSize, LPSTR IpszCmdLine) 
{ 
if (wHeapSize > 0) | 
UnlockData (0) ; 
return 1 ; | 


// Later add Thunking code here 

WORD __export FAR PASCAL AddNums16(WORD a, WORD b) 
it | 

return (a + b); 


i 

void _export FAR PASCAL Beep16(void) 

i | 
MessageBeep(MB_OK); | 

} 

void __export FAR PASCAL Ucasel6(LPSTR pString) 

{ | 


AnsiUpperBuff(pString, (UINT) Istrlen(pString)); 
: | 


to the 16-bit segment/ 
offset equivalent 

of Windows 3.x. 
Thunking also does 


LISTING 1 Build a Simple 16-Bit DLL. This 16-bit DLL contains a 

few simple 16-bit functions called from the 32-bit thunking 

DLL. Thunking code will be added right after the standard LibMain 

entry routine. The three functions illustrate different types of 
parameter usage that must be handled by the thunk compiler. 
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Thunk script — defines the 
16-bit functions to be called 


32-bit VB4 16-bit VB4 


THUNK.EXE & THUNK32.LIB: 
Thunk compiler — creates 


assembler code to establish 
the thunking layer 


32-bit application 
with calls to 16-bit 
DLL functions 


ML.EXE: Macro assembler — 
creates16-bit and 32-bit OBJ 


32-bit =f 
C Compiler | 


32-bit DLL 


modules to be included in 


each DLL project 


16-bit ; 
C Compiler 


16-bit Windows 
application 


RC.EXE: i 
Resource compiler 4.0 or | 
greater — marks DLL (= 


16-bit DLL |f 


Thunking layer changes 32-bit 
flat pointers to 16-bit segmented 
pointers, switches stacks, and 
converts return values 


Third-party 16-bit DLL 


(optional) 


Figure | Assemble Your Tools. You'll need 32-bit and 16-bit C compilers, a thunk compiler, MASM, and a number of utilities. The 
middle column shows the tools and process for creating the thunking layer. The thunk script is an ASCII text file placed into 
the thunk compiler. Assembler code produced from the thunk compiler is placed in the assembler, which produces OBJ files included 
in the C projects that produce the thunking layer. 


tutorial, it contains a number of errors and 
omits animportant declaration. For example, 
Q125715 leaves out the semicolon in some 
code (suchas: enablemapdirect3216 = true;) 
but I noticed that other statements ended 
with C-stylesemicolons, soaddingonesolved 
the problem. 

Before starting a thunking project you 
must have the right tools. It took me longer 
to determine which tools and utilities I 
needed, to find them, and to figure out when 
to use them, than it took to create the code. 
Of course the results of my search make 
your job much easier. 

To compile the codein this article you'll 
need 16-bit and 32-bit C compilers that are 
compatible with Microsoft OBJ and LIB 
formats, and a number of utility programs 
to create the thunking DLLs (see Figure 1). 
I spent quite a bit of time searching the 
MSDN CDs while posting and re-posting 
CompuServe messages looking for the right 
assembler and resource compiler. 


Because you are creating 32-VB apps, 
you'll need 32-bit tools for thunking. Obvi- 
ously you need Windows 95 and a 32-bit C 
compiler. I used Microsoft Visual C++ 2.0 for 
the 32-bit compiler, and Visual C++ 1.51 for 
the 16-bit compiler, which both come on 
thesame CD. You donot need the subscrip- 
tion versions or Visual C++ 4.0 to create the 
DLL thunking code I'll discuss. The other 
major C compilers on the market should 
compile the code properly, provided they 
are compatible with the THUNK32.LIB file 
and can assemble the code produced by 
the thunk compiler. 

The thunk compiler is on the Win32 SDK 
CD, which comes in the MSDN Level 2 set of 
CDs. The Win32 SDK is not on the single CD 
Level 1 MSDN. Also, you will need the 16-bit 
resource compiler from the Win32 SDK, and 
the Macro Assembler fromthe Device Driver 
Kit CD in the MSDN Level 2 CD. I'll explain 
the directory names and file names as | 
discuss their use. 


Forthesake ofillustrating thunking tech- 
niques, I'll discuss only the 32-bit-to-16-bit 
thunk in this article. However, I have added 
a 16-bit-to-32-bit thunk example in the code 
available for download on the VBP/J Forum 
on CompuServe. 


CREATE YOUR 16-BIT DLL 
When creating a thunking system it’s best 
to start simple. To illustrate thunking tech- 
niques, I created a simple 16-bit DLL that 
doesn’t have a thunking layer. It’s impor- 
tant to ensure that the 16-bit functions work 
properly before adding the thunking layer. 
Icreated this simple 16-bit DLL purely 
to demonstrate thunking techniques (see 
Listing 1). To build this DLL—called 
MYDLL16.C—start 16-bit Visual C++ 1.5x, 
start a new project, and select DLL from 
the project type list. Be sure the Microsoft 
Foundation Classes check box is off. Ac- 
cept all defaults including the large 
memory model default, and let Visual C++ 
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create the DEF file. Later you’ll need to 
modify the DEF file to add thunking. 
MYDLLI16.C consists of four functions. 
LibMainQ is the standard entry point found 
in all 16-bit DLL programs. The other three 
functions are trivial ones that will be called 
from 16-bit VB, and later from the 32-bit DLL 
after thunkingis added. Specifically, Beep16 
simply causes the speaker to beep, 
AddNums16 adds two integers together 


WB4) 


Attribute VB_Name = "Modulel" 
Option Explicit 
#If Win32 Then 


(ByVal s As String) 


Declare Function AddNums32 Lib "MYDLL32.DLL" (ByVal a _ 


AsLong, ByVal b AsLong) As Long 
#Else 


Declare Sub Beepl6 Lib "MYDLL16.DLL" () 
Declare Function AddNums16 Lib "MYDLL16.DLL" _ 

(ByVal a As Integer, ByVal b As Integer) As Integer 
Declare Sub Ucasel6 Lib "MYDLL16.DLL" _ 


(ByVal s As String) 
#End If 


Declare Sub Beep16 Lib "MYDLL32.DLL" () 

Declare Function AddNums16 Lib "MYDLL32.DLL" (ByVal a _ 
As Integer, ByVal b As Integer) As Integer 

Declare Sub Ucasel6 Lib "MYDLL32.DLL" _ 


and returns the result, and Ucasel6 con- 
verts a string to upper case. These func- 
tions demonstrate how thunking works with 
different parameter types. 

To test the 16-bit DLL, start the 16-bit 
version of VB and open a new project. 
Remove the Form] file and insert a new 
module to create a simple formless project 
that consists of declarations and the code 
in Sub Main (see Listing 2). Notice the use of 


Sub Main() 


Dim x As Integer, s As String 


#If Win32 Then 


MsgBox "We are in 32 bit mode." 
MeuGathss2npite Del 

x = AddNums32(2, 3) 

MsgBox "2 +3 =" & Str$(x) 


#Else 
#End If 


Call Beepl6 


x = AddNums16(3, 4) 
MsgBox "3 +4 =" & Str$(x) 


s = "My String" 


Call Ucasel6(s) 


MsgBox "After call: " & §$ 


End Sub 


MsgBox "We are in 16 bit mode." 


Call 16 bit DLL 


MsgBox "Before call: "& S$ 


the #If Win32 statement to change the DLL 
declarations for 16- and 32-bit modes. The 
16-bit version will call the 16-bit DLL, and 
the 32-bit version will call the 32-bit DLL I'll 
describe later. 

After compiling, move the compiled 
MYDLL16.DLL into your’ WIN- 
DOWS\SYSTEM directory. Alternatively, 
you can fully qualify the DLL path in the 
Declaration statement, but this will cause 


LISTING 2 Call 16-Bit Functions. This VB code calls 16-bit DLL functions from either 16-bit or 32-bit VB4. The #Ilf Win32 statement 
changes the declarations so 16-bit VB programs will call the 16-bit DLLs, but 32-bit programs will call the same functions in 
the 32-bit DLL with thunking added. Hence the same VB code can be used for both 16-bit and 32-bit projects. 


A data aware, multi-column list box with 3D display effects, column headings, display j 


output formatting, and no 64K data limit. 


Acontrol to provide 3D display effects for the form itself; no matter what its. 


BorderStyle property is set to. 


Dynamic arrays that make it easy to insert, delete, add; locate, and sort data 


elements. 


A way to handle multidimensional collections of data, including ways to store 


information in a sorted order. 


A complete library of string handling functions that includes pattern matching, range 
checking, data conversions, and sub-string manipulation. 


Now Visual Basic has these features and more with ... 
Vantage Control Set Vantage Power Strings 


An affordable custom control library with 
both VBX and OCX versions. 
List Price $69.00. 


String management and dynamic array 
utilities for both VB3 and VB4. 
List Price $ 59.00. 


For a limited time purchase both for only $99.00 


For more information see our home page on the World Wide Web: _ http://www.icon.com/~vantage/ 


Vantage Control Set and Vantage Power Strings are 
trademarks of VantagePoint Software, Inc. Visual Basic 
is a registered trademark of Microsoft Corporation. 
Prices may vary outside North America. 


VantagePoint Software, Inc. 

1619 E. Lakeview Drive 
Bountiful, UT 84010 
801-292-5344 Fax 801-292-3142 
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User Tip 


CLOSING ALL OPEN 
FILES IN AN 
APPLICATION 


Use the Close statement without a 
file number and Visual Basic will 
close all files opened by your 
application. 


—Douglas Haynes, 
received on CompuServe 


SEND YOUR TIP 

If it’s cool and we publish it, we'll pay 
you $25. If it includes code, limit code 
length to 10 lines if possible. Be sure 
to include a clear explanation of what 
it does and why it is useful. Send to 
74774.305@compuserve.com or 
Fawcette Technical Publications, 209 
Hamilton Ave., Palo Alto, CA, USA, 
94301-2500. 


problems later when the 32-bit DLL needs 
to find the 16-bit DLL, so I recommend that 
for your first thunking effort you copy all 
the DLLs to WINDOWS\SYSTEM. 


COMPILE THE THUNK SCRIPT 

Now that the 16-bit functions are finished, 
create a script for the thunk compiler. 
Thethunk compiler uses script statements 
to generate a file containing assembler 
code functions. The assembler language 
functions are the core of thunking—they 
do the segment and stack fixes that let the 
32-bit DLL call 16-bit functions. Although 
the assembler code could theoretically 
be coded by hand, it is quite complex and 
best left to the thunk compiler. 

The parameters and return types of 
each 16-bit function are defined in the 
thunk script so the thunk compiler can 
generate the appropriate code for each 
function. Create a file with these script 
statements using Notepad or any ASCII 
text editor, and save it as 32TO16.THK: 


enablemapdirect3216 = true; 
typedef char *LPSTR; 
void Beepl6(void) 
{ 
} 
int AddNums16 (int a, 
{ 
} 
void Ucasel6 (LPSTR IpString) 
{ 

TpString = inout; 
} 


int b) 


The first statement, enablemapdir- 
ect3216 = true;, indicates mapping from 32- 
bit to 16-bit. The typedef statement creates 
along string pointer type that is used in the 
Ucase16Q parameter list. The functions are 
declared C-style starting with return type, 
then function name, argument list, and a 
pair of braces. 

_ Return type void indicates there is no 
return value—a SUB in Basic. The 
IpString=-inout; statement tells the thunk 
compiler that datain the string will be passed 
to and from the 16-bit DLL, so the segment/ 
offset conversions must occur both ways. 

The 32-bit thunk compiler program 
THUNK.EXE can be found on the Win32 
SDK CD of MSDN Level 2, in directory 
WIN32SDK\MSTOOLS\BIN\I386. Direc- 
tory names sometimes change in SDKs, 
so if you have trouble finding this direc- 
tory, do a file search and be sure you 
select the 32-bit Intel version that is 
usually in an 1386 subdirectory. 

While you have the Win32 SDK CD 
loaded, you should also copy 
THUNK32.LIB because you will need it 
later in your 32-bit DLL project. 
THUNK32.LIB is in the\WIN32SDK\ 
MSTOOLS\LIB\I386 directory. To com- 


pile the thunk script, open a DOS Prompt 
window (yes, it’s still there in Windows 
95) and run the thunk compiler with this 
command line: 


thunk -t thk 32to16.thk -o 32tol6.asm 


The -t thk option will prefix all the 
assembler routines with a thk_ prefix. 
The -o 32tol6.asm option (lowercase 
“o”) indicates the output file name for 
the assembly language routines. 


ASSEMBLE THE THUNK OUTPUT 

Now that you have an assembler language 
output file, you need to assemble the file 
into OBJ object code modules that can be 
included in each DLL project. Assemble the 
single ASM file twice with different com- 
mand line switches to produce separate 32- 
bit and 16-bit OBJ files. You must use 
Microsoft Macro Assembler (MASM) 6.11 
or later—MASM 5.0 won't do. When | got to 
this step, I found that, lo and behold, Visual 
C++ does not come with a separate assem- 
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bler. And an inline assembler won’t cut it for this either. 

Time to dig out the MSDN CD set again. Fortunately, MASM6.11 
can be found on the Device Driver Kit CD as ML.EXE in directory 
\DDK\BIN\I386\FREE. Again, directory names may change. 

To confirm the version number, simply execute ml at the DOS 
prompt with no command-line arguments. I created a simple two- 
line BAT file to execute the assembler twice so the assembler will 
produce the THK32.0BJ and THK16.OBJ files that I added to the 
DLL projects (the underscore should be removed and the two lines 
combined into one): 


ml /DIS_32 /c /W3 /nologo /coff /Fo thk32.obj 32tol6.asm 
ml /DIS_16 /c /W3 /nologo /Fo _ thk16.obj 32to016.asm 

Now create the 32-bit DLL called MYDLL32.C (see Listing 3). It’s 
quite different from a 16-bit DLL. The LibMain entry point is 
replaced by DilMain. The 32-bit standard entry point contains a 
switch statement that checks whether the DLL is being loaded or 
unloaded for a new process or a new thread within a process. 

For this program, simply break out of the switch in all cases. The 
DllMain entry code starts with a call to thk_ThunkCon-nect320.. 
This assembly-language function was produced by the thunk 
compiler. It loads the 16-bit DLL into memory and calls the corre- 
sponding 16-bit thunk code to establish the flat thunking layer. 

If the 16-bit DLL cannot be loaded, the call returns a non-zero 
code, and MYDLL32 produces a beep and returns FALSE so the 32- 
bit DLL will not load. When this happens, VB reports it was unable 
to load the 32-bit DLL but does not indicate why. I added 
MessageBeepQ so I know the 32-bit DLL loaded, but I get a beep if 
there is a problem loading the 16-bit DLL. 

Functionthk_ThunkConnect32Q starts with the thk_prefix speci- 
fied on the thunk compiler command line-t switch. A declaration has 
been added for the function, with an “extern” keyword to tell the 
linker that this function can be found in an external module. This 
important declaration is missing from the MSDN Q125715 article, 
and if you leave it out the compile will fail with an “unresolved 
external reference” message. I also added a simple 32-bit function, 
AddNums320, toillustratetheWin32__declspec(dllexport) DWORD 
WINAPI keywords for exported functions. 

You also need to modify the EXPORTS section of the 
default MYDLL32.DEF file created by Visual C++ to add 
thk_ThunkData32 and all the 16-bit functions your code will 
call. The ASM code produced by the thunk compiler con- 
tains 32-bit stubs with exported names that match the real 
16-bit functions. These stubs do fix-up code, and then call 
the real 16-bit function. The new EXPORT section in 
MYDLL32.DEF is: 


// MYDLL32.C 
#Hinclude <windows.h> 
extern BOOL WINAPI thk_ThunkConnect32(LPSTR, LPSTR, 
HINSTANCE, DWORD); 
__declspec(dllexport) DWORD WINAPI AddNums32 (DWORD, 
DWORD) ; 
// The standard 32 bit opening, with thunking added 
BOOL WINAPI D11Main (HINSTANCE hDLL, DWORD dwReason, 
LPVOID 1pReserved) 
{ 
if (!thk_ThunkConnect32 ("MYDLL16.DLL", 
"MYDLL32.DLL", 
HOLL, 
dwReason) ) 
{ 
MessageBeep(MB_ICONEXCLAMATION) ; 
return FALSE; 
}°// end if 


EXPORTS 
thk_ThunkData32 
Beepl6 
AddNums16 
Ucasel6 
AddNums32 


To compile the 32-bit DLL, start 32-bit Visual C++ 2.0 or later and 
create a new project (File, New, Project) and choose project type 
DLL. Add file MYDLL32.C from Listing 3, add THK32.OBJ, which you 
created with the thunk compiler and assembler, and add 
THUNK32.LIB, which you copied from the Win32 SDK. 

After your compile is complete, MYDLL32.DLL will be in a 
subdirectory named WINDEBUG created by Visual C++ under 
your project directory. Movethis DLLto your WINDOWS\SYSTEM 
directory. If you get any “unresolved external” messages, recheck 
all the function names, recheck your thunk script, recheck that 
the OBJ and LIB files were properly added to the project, and 
recheck the thk_ThunkConnect32Q0 function declaration. 


MODIFY THE 16-BIT DLL 

You must add code to MYDLL16.C to complete the 16-bit thunking 
layer (see Listing 4). DllEntryPoint calls function 
thk_ThunkConnect16Q created by the thunk compiler. You can 
add the DilEntryPoint declaration and function anywhere to 
MYDLL16.C—a good place is right after LibMain. Notice that the 
standard LibMain function is unchanged. No other changes are 
needed in the C code, although some changes are required in the 


// declaration for function from thunk compiler 

extern BOOL PASCAL thk_ThunkConnect16(LPSTR, LPSTR, 
WORD, DWORD); 

// required for thunking 

BOOL FAR PASCAL __export D11EntryPoint(DWORD dwReason, 
WORD hInst, WORD wDS, WORD wHeapSize, 
DWORD dwReserved, WORD dwReserved2) 


{ 
if ( !thk_ThunkConnect1l6("MYDLL16.DLL", 
"MYDLL32.DLL", hInst, dwReason)) 
{ 
return FALSE; 


} 
return TRUE; 


LISTING 4 Create 16-Bit Thunking. Add this code to any 16-bit 
DLL that will be called through the flat thunking layer. 


DllEntryPoint is called by the 32-bit thunking layer. The 
thk_ThunkConnect16 function completes the link to and from the 
32-bit DLL. 


switch (dwReason) 


case DLL_PROCESS_ATTACH: 
break; 
case DLL_THREAD_ATTACH: 
break; 
case DLL_THREAD_DETACH: 
break; 
case DLL_PROCESS_DETACH: 
break; 
} // end switch 
return TRUE; 
} 
__declspec(dllexport) DWORD WINAPI AddNums32 
(DWORD a, DWORD b) 
{ 


return (a + b); 


LISTING 3 Add a 32-Bit Thunking Layer. Use this 32-bit DLL to call the 16-bit functions through the thunking stubs linked in from the 
thunk compiler. The thk_ThunkConnect32 function creates the thunking link to the 16-bit DLL. If this critical function call fails, 


the DLL beeps and fails to load. 
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MYDLLI16.DEF file. The EXPORTS section 
must be modified, and an IMPORTS section 
must be added. This code is identical for 
adding thunking to all 16-bit DLLs: 


IMPORTS 
C16ThkSLO1 = KERNEL.631 
ThunkConnect16 = KERNEL.651 


EXPORTS 
WEP PRIVATE 
THK_THUNKDATA16 @1 RESIDENTNAME 
DI1EntryPoint @2 RESIDENTNAME 


Finally, you must modify the 16-bit DLL 
project (click on Project, then Edit) to add 
THK16.OBJthat was produced bythethunk 
compiler and assembler. Compile 
MYDLL16 and you should get no errors 
and no warnings. 

‘By now you’re probably more than 
ready to test your thunking calls. The 
last step should take you five minutes 
(although it took me several days to find 
the right resource compiler necessary to 
complete this step). You must run the 
resource compiler program RC.EXE to 
mark the 16-bit DLL version as 4.0. Other- 
wise, the 32-bit DLL will not be able to 
load it. The trick is to find the right re- 
source compiler. 

The 16-bit and 32-bit resource compil- 
ers that come with VB4 won’t do—you 
need a resource compiler version 4.0 or 
later that supports the “-40” command- 
line argument. The Win32 SDK CD con- 
tains five different copies of 
RC.EXE—you need the 16-bit version, 
which is located in \WIN32SDK\ 
MSTOOLS\BINW16. 

To confirm the version, run RC.EXE 
from the DOS prompt with no arguments, 
or with /? to be sure it supports the “-40” 
command-line argument. Then run it to 
mark your 16-bit DLL. You must repeat 
this step every time you recompile the 16- 
bit DLL: 


re -40 MYDLL16.DLL 


Be sure to move both compiled DLLs to 
your WINDOWS\SYSTEM directory, or 
MYDLL32.DLL may have problems trying to 
load MYDLL16.DLL. 

It’s time to test! Start 32-bit VB4 and open 
the project created using Listing 2. Thanks 
to the #If Win32 statement, the code now 
calls the 32-bit DLL, and also calls an extra 
function, AddNums320, which is in the 32- 
bit DLL only. VB loads both DLLs on the first 
call to AddNums32. If MYDLL32 is unable to 
load MYDLL16, it will fail at this point. 

If you hear the beep, you know that 
MYDLL32 loaded, but was unable to load 
MYDLLIG6. If MYDLL16 fails to load, be sure 
you ran RC.EXE to mark it after your last 
compile, recheck the code _ to 


thk_ThunkConnect160, and recheckall the 
DEF files in both DLLs, making sure all your 
16-bit functions are inthe EXPORTS section 
of the 32-bit DLL. 

A good source of information for de- 
bugging thunks is the Microsoft Knowl- 
edge Base article Q133722 (GO MSKB on 
CompuServe). After VB loads a 32-bit 
DLL it only unloads it when the project is 
closed or you modify the Declare state- 
ment. If you recompile the 32-bit DLL, 
you won’t be able to replace the DLL file 


until you close and reopen the VB project. 

Well, there you have it. You can now 
call your 16-bit DLL from a 32-bit DLL. 
And here’s one last tip. What if you don’t 
have the source code for the 16-bit DLL 
you’re trying to call? You can’t add the 
needed thunk connect function, or link 
in the OBJ files, but you could write a 32- 
bit DLL that thunks to your own 16-bit 
DLL that in turn calls the third-party 16- 
bit DLL with normal 16-bit calls. But be 
careful with those pointers. % 
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Reading the 


application for 
both in-house and 


remote use. 


ould you like to have your com- 
W puter request that processing 

be done by another computer 
on the network? Would you like to be noti- 
fied when jobs running on an unattended 
computer run to completion? How about 
getting “almost workflow” benefits with 
minimal changes to your Excel, Word, and 
Access applications? Maybe these features 
should come with built-in fault tolerance, 
auditing, administration, and logging capa- 
bilities. And of course, you want to get all 
these features for free. did, too, and! didn’t 
have to look any further than Microsoft’s 
Mail API (MAPI) as implemented in VB’s 
MAPI.VBX. 

To take advantage of mail technology 
from within your VB application, youneed 
to start with a generic program to read 
your mail (if e-mail terminology is new to 
you, look at the accompanying sidebar, “A 
Brief Introduction to Mail Systems”). 


Peter Vogel is the applications supervisor at 
Champion Road Machinery, a Microsoft 
Certified Solution Developer, the father of 
two terrific boys, and Jan’s husband (not 
necessarily in that order). He can be reached 
at peter.vogel@odyssey.on.ca. 


Mail 


Sub LogInMail 
"pick up any new mail on startup 
MAPISESSION.DownloadMail = True 
"piggyback on existing mail session 
MAPISESSION.NewSession = False 
"start session 
MAPISESSION.Action = 1 


Let’s call this program MailHandler 
(MAILHAND.EXE) and create it as a single 
form with two controls, MAPISESSION.VBX 
and MAPIMESSAGES.VBX. 

MailHandler’s code starts by logging 
onto the mail session of the computer it is 
running on: 


Bs 
g 
ES 


E 


Process A Message | 


tee oo 


pa cet > Other Functionality 


Mail Automation from Start to Finish. Processing mail consists of logging 
onto the existing Mail session and repeatedly building lists of new mail. Each 
list must be processed, looking for messages to be handled by MailHandler. When a new 
mail list adds no new messages, processing ends. 


FIGURE | 
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"pass session ID to message VBX 
MAPIMESSAGES.SessionID = _ 
MAPISESSION.SessionID 
End Sub 


Working with MAPISESSION estab- 
lishes the mail session. All handling of the 
mail is done through MAPIMESSAGE, 
which is passed the ID for the session 
from MAPISESSION. This code assumes 
that the user has already logged onto the 
mail system. If your standard is to include 
mail in your users’ startup groups, it'll 
work. Otherwise, you must set the logon 
information in your code: 


MAPISESSION.UserName 
MAPISESSION. Password 


"MailUser" 
"UserPassword” 


Microsoft Mail gives you a third option: 
put Userld and Password information in 
the user’s INI file for automatic logon at 
startup (an unattended computer at my 
office is configured in this manner). The 
last thing you need to do is shutdown the 
mail session you created using: 


Sub LogOutMail 
MAPISESSION.Action = 2 
End Sub 


STRATEGY, FAILURE, RECOVERY 

In my opinion, you have three usable 
strategies for processing mail. The first 
method requires that you start 
MailHandler in the StartUp Group and log 
on at startup, check for Mail in a Timer 
event and process any messages that re- 
quire it, log out, and shut down. 

In this scenario, the logon code goes in 
your form’s Load event and the logout 
code goes in the form’s Close event. This 
strategy consumes the most resources 
over the longest period of time, but it also 
has the smallest performance hit when 
mail is actually processed. You will need 
to add the timer control to your form in 
order to use this strategy. 

To use the second method, you also 
place the MailHandler program in the 
StartUp Group, log onto mail in the Timer 
event, process mail, andlog out. The logon 
and logout code go in the Timer event. 

This consumes fewer resources over a 
shorter period of time, but it also causes a 
bigger memory hit when it’s time to pro- 
cess mail. As with the first strategy, you'll 
need to add a timer control to your form. 

The third method causes MailHandler 
to start automatically when new mail is 
received, log on, process mail, and log 
out. The logon code goes in the Load 
event and the logout code goes in the 
Close event. This method consumes the 
least amount of resources and does so 
the least frequently, but causes the big- 
gest resource hit when it is time to 


‘define what the keywords to look for 
‘in the subject line of the messages 
Global Const RUNPROGRAM = "RUN PROGRAM" 
Global Const DISPLAYATTACHMENT = "DISPLAY ATTACHMENT" 
Global Const DISPLAYNOTIFICATION = "NOTIFY MESSAGE" 
Declare Function GetModuleUsage% Lib "Kernel" (ByVal hModule As Integer) 
Declare Function FindExecutable% Lib "shell.d11" (ByVal lpszFile$, ByVal 
IpsDir$, ByVal IpszResult$) 
Sub ProcessMail 
"read all unread mail and respond to 
‘mail needing processing 
Dim stzType As String 
Dim stzId As String 
Dim ing As Integer, ingUnRead As Integer 


MAPIMessages.FetchUnreadOnly = True 
MAPIMessages.Action = l 
ingUnRead = MAPIMessages.MsgCount 
While ingUnRead > 0 
For ing = 0 To ingUnRead - 1 
MAPIMessages.MsgIndex = ing 
stzType = CheckType((MAPIMessages .MsgSubject) ) 
If stzType > " " Then 
ProcessMessage MAPIMessages, stzType, ing 
ingUnRead = ingUnRead - 1 
End If 
Next ing 
"check to see if any new mail recieved 
MAPIMessages.FetchUnreadOnly = True 
MAPIMessages.Action = 1 
If MAPIMessages.MsgCount > ingUnRead Then 
ingUnRead = MAPIMessages.MsgCount 
Else 
ingUnRead = 0 
End If 
WendEnd ProcessMail 
Function CheckType (stzSubject as string) as string 
If Instr(UCase(stzSubject),RUNPROGRAM) Then 


CheckType = RUNPROGRAM 
Elself Instr(UCase(stzSubject) ,DISPLAYNOTIFICATION) Then 
CheckType = DISPLAYNOTIFICATON 


Elself Instr(UCase(stzSubject) ,DISPLAYATTACHMENT) Then 
CheckType = DISPLAYATTACHMENT 
Else 
CheckType = 
Endif 
End Function 
Sub ProcessMessage(cntMailControl as control 
integer) 
"passed the type of mail, 
"call the routine to process it 
Select Case (stzType) 
Case DISPLAYNOTIFATION 
DisplayNotification cntMailControl, ingPos 
Case RUNPROGRAM 
RunProgram cntMailControl, ingPos 
Case DISPLAYATTACHMENT 
DisplayAttachment cntMailControl, ingPos 
Case Else 
MsgBox "Mail Type " & stzType & " is recognized _ 
but no routine exists to process it." 
End Select 
End If 


,stzType as string, ingPos as 


— 

LISTING 1 The Check is in the Mail? The routine charged with checking for interesting 

mail, CheckType is called from within ProcessMail and returns the type of mail 

just read. This is passed to ProcessMessage, which finds the message and calls the 
appropriate routine to process it. 


process new mail. an “Unable to read from device NET- 


Initially, | went with the first method 
for implementation at my company. How- 
ever, at the time we implemented the 
system, we were having some problems 
with our network and this method turned 
out to be unreliable: I’d leave the com- 


puter alone for a while and return to find 


WORK” message on the screen. 
Converting to the third method from 
the first consisted of putting an End state- 
ment after the mail processing and a line 
in the MSMAIL.INI file. It seemed simple 
enough, so we went with it. Actually, we 
left both processes in with a command- 


hitp://www.windx.com 
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stzKeywords (2,2) 


\VWB3 ElseIf Instr(stzKeywords(1,2), "Excel.Exe") > 0 _ 
x Then 
Sub RunProgram (cntMail as control, ingPos as integer) SetExcelCommand stzKeywords(4,2),_ 
"passed a mail control, load the keywords stzKeywords(2,2) 
"array with the keyword to search for, Else 
"get the name of the program and any parameters. stzCommandLine = stzCommandLine &"" _ 
"check for special EXE’s that require funny & stzKeywords(4,2) 
‘formatting of their command lines End If 
Dim stzKeywords(4,2) Endif 
Dim stzCommandline as string WaitForCompletion Shell(stzKeywords(1,2) &" " _ 
stzKeywords(1,1) = "Program:" & stzCommandLine,4) 
stzKeywords(2,1) = "Document:" Endif 
stzKeywords(3,1) = "Macro:" End Sub 
stzKeywords(4,1) = "CommandLine:" Sub ParseText (stzKeywords() as string,stz as string) 
ParseKeywords stzKeywords(), cntMail.Text "passed a 2-D array of keywords and a 
If stzKeywords(1,2) > " " Then " string, add the value found for the 
If stzKeywords(2,2) > " " Then " keyword to the array 
stzCommandLine = stzKeywords(2,2) Dim stzWork as string 
Endif Dim ing as integer 
If stzKeywords(3,2) > " " Then stzWork = Trim(stz) 
If Instr(stzKeywords(1,2), "MSAccess.Exe") > 0 _ For ing = 0 to UBound(stzKeywords()) 
Then ingWordPos = Instr(stzWork,stzKeywords(ing,1)) 
stzCommandLine = stzCommandLine & "/X " & _ If ingWordPos > 0 Then 
stzKeywords (3,2) ingTabPos = Instr(ingWordPos,stzWork,Chr(9) ) 
ElseIf Instr(stzKeywords(1,2), "WinWord.Exe") > _ ingCRPos = Instr(ingWordPos,stzWork,Chr(13) ) 
0 Then stzKeyWords(ing,2) = Mid$(stzWork,ingTabPos _ 
stzCommandLine = stzCommandLine & "/m" & _ + 1,ingCRPos-ingTabPos -1) 
stzKeywords(3,2) End If 
Elself Instr(stzKeywords(1,2), "Excel.Exe") > 0 _ Next ing 
Then End Sub 
SetExecIMacro stzKeywords(3,2), _ Sub WaitForCompletion(ingTaskId as Integer) 
stzKeywords(2,2) Sub RunProgram(cntMail as Control) 
Else "passed a taskid, do not return until one of 
stzCommandLine = stzCommandLine &" " _ "the instances of the task’s module stop 
& stzKeywords(3,2) Dim ingInitialUsage As Integer 
End If If ingTaskId <> 0 Then 
Endif ingInitialUsage = GetModuleUsage%(ingTaskId) 
If stzKeywords(4,2) > " " Then If ingInitialUsage > 0 Then 
If Instr(stzKeywords(1,2), "MSAccess.Exe") > 0 _ While GetModuleUsage%(ingTaskId) >= _ 
Then ingInitialUsage 
stzCommandLine = stzCommandLine & "/C " & _ DoEvents 
stzKeywords(4,2) Wend 
ElseIf Instr(stzKeywords(1,2), "WinWord.Exe") > _ End If 
0 Then End If 


SetWordCommand stzKeywords (4,2) End Sub 


LISTING 2 Looking for Keywords. The ParseText routine provides a standard way for each message-type routine to find its keywords. 
With VB4’s improved variants, you can implement this as a function. RunProgram is the workhorse routine in MailHandler 

and shows how the ParseText routine is used. WaitForCompletion uses a Windows API call to pause MailHandler until the program 
completes. 
ee 2 a = End 


Schedule Notification been 


Sub Timer_Timer() 
ProcessMail 


| | End If 
Sub UnLoad(Cancel as integer) 


LogOutMail 
End Sub 


To get MSMAIL to run MailHandler 
whenever it received new mail, we added 
this line to the MSMAIL.INI file on the 
computer that was to process the mail: 


FIGURE 2. It’s a First. This is a standard first message for any new tool. The displayed date 


and time let the recipient know if the message had been received on time. AUTO=3.0; ;; ;APPEXEC.DLL;C:MAILHAND. EXE; _ 
0 010000000000000;_ 
line option to switch between them: LogInMail Process application system mail;:; 
If Command() = "/T" 

Sub Form_Load() "strategy 1 We also had to ensure that 
" check to see if MailHandler Timer.Enabled = True APPEXEC.DLL was in the Windows/Sys- 
" already running and exit if so. Else tem directory of the computer. APPEXEC 
If App.PrevInstance Then "strategy 2 is supposed to be a custom DLL that you 
End Timer.Enabled = False create to pass parameters to the program 
End If ProcessMail called when new mail is received. Be- 
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_MAPT WORKFLOW 


UNREGISTER A DLL WITH THE RIGHT 
MOUSE BUTTON IN WIN95S 


Create a file called UNREGDLL.REG, and add this to the file: 


REGEDIT4 


[HKEY_CLASSES_ROOT\d11file\shel1] 
@="0pen" 


[HKEY_CLASSES_ROOT\d11file\shell\open] 


@="" 


[HKEY_CLASSES_ROOT\d11file\shell\open\command] 
@="C(:\\windows\\system\\regsvr32.exe 41" 


[HKEY_CLASSES_ROOT\d11file\shel1\Unregister] 


[HKEY_CLASSES_ROOT\d11file\shel1\Unregister\command] 
@="(:\\windows\\system\\regsvr32.exe /u %1" 


Run the file in Windows 95. Now, when you right-click on a DLL or OCX file 
in Explorer, the Unregister command will appear, allowing you to unregister 
a DLL quickly. You can delete the REG file after you run it the first time. 

To register and unregister a DLL or OCX from the command line, use 
RegSur to register a 16-bit DLL or OCX and use RegSur32 to register a 32-bit 
DLL or OCX. To unregister a DLL, use the same command with the /u 


switch. For example: 


RegSvr32 msrdo.d11 
RegSvr32 /u msrdo.dl1 


—A. Nicklas Malik 
received by e-mail 


SEND YOUR TIP 


registers the RDO dll 
unregisters the RDO dll 


If it’s cool and we publish it, we'll pay you $25. If it includes code, limit code length to 
10 lines if possible. Be sure to include a clear explanation of what it does and why it 

| is useful. Send to 74774.305@compuserve.com or Fawcette Technical Publications, 
209 Hamilton Ave., Palo Alto, CA, USA, 94301-2500. 


cause MailHandler doesn’t need any pa- 
rameters, youcan use APPEXEC, adummy 
DLL supplied with MSMail. 

Now you're ready to have MailHandler 
see what’s in the mail. The trick is to 
recognize which messages can be pro- 
cessed automatically, and which mes- 
sages are intended to be read by the user 
(see Listing 1). 

Define three types of mail to be pro- 
cessed. automatically: display a message, 
run a program, and display an attachment. 
All three types will make their appearances 
in this article and, as you will see, defining 
new types would be easy (see Figure 1). 

You can use the MailType property to 
identify the mail to be processed. When 
you create your mail, set the MailType 
property of your message to any value 
(its default value is to be unset). 

When reading the mail, you can check 
the MailType property of each message 
to identify your “system managed” mail. 
Setting MailType also converts the mail 
to noninterpersonal mail so that it does 
not appear in your user’s in-box. 

I chose not to use MailType because | 


wanted to be able to create and read 
MailHandler messages on the fly from within 
the regular mail client. In case things went 
wrong, | also wanted to be able to audit the 
system just by reading the mail in our com- 
puters’ in-boxes and sent-mail folders. 

Inaddition, Microsoft’s documentation 
suggests that MailType is not supported 
for all mail services providers. Finally, the 
receipt of non-IPM mail will not trigger the 
automatic execution of a program. 

To deal with these situations, 
MailHandler checks for keywords in the 
subject line of mail messages using the 
InStrO function. These keywords deter- 
mine if a message should be processed 
and what routine should be used to handle 
the message. InStr(Q allows the subject 
line of the message to contain other infor- 
mation (for audit purposes) and allows 
forwarded and reply mail to be processed 
by MailHandler. 

Once MailHandler finds amessage with 
a keyword heading, it opens the message 
and reads it, looking for more keywords. 
This means that when MailHandler wakes 
up and reads the mail, it can ignore mail 


that is already read because it’s already 
been processed. 

The ProcessMail routine creates a list 
of unread mail and runs through it looking 
for interesting subject headings. It pro- 
cesses the subject headings by calling an 
appropriate handler routine. When all the 
unread mail is checked, ProcessMail 
checks to see if any new mail has been 
received while it was busy and checks it. 
If none has, ProcessMail ends. 


THE GOOD STUFF 

Now that MailHandler can read the mail, 
what do you want it to do with the mes- 
sages? The simplest action you probably 
want the program to take is to display a 
notification on the screen. 

The DisplayNotification routine reads 
the text of the mail message looking for 
the keyword “Notify:” followed by a tab. 
Whatever follows the tab and precedes 
the next carriage return is displayed ina 
message box on the screen. A message 
with the Subject “Notify Message - a test 
message” with the text: 

Notify: Hello World 

will cause MailHandler to display “Hello 
World” on whatever computer it is run- 
ning on (see Figure 2). Here’s the 
DisplayNotification routine: 


Sub DisplayNotification(cntMail as _ 
Control, ingPos as integer) 

"passed a mail control, load the 

"keywords array with the keyword to 

"search for, get the value of the 

"message and display it 

Dim stzKeywords(1,2) 

MAPIMessages.Index = ingPos 

stzKeywords(1,1) = "Notify:" 

ParseKeywords stzKeywords(), _ 
(cntMail.Text) 

If stzKeywords(1,2) > " " Then 
MsgBox Now() & ": "& _ 

stzKeywords(1,2),16 
End If 
End Sub 


Now you might ask, “What possible use 
could this routine be?” We have MailHandler 
running onacomputer in our security guard- 
house. Several jobs running on unattended 
computers at night send Notify-type mail to 
our guards when they reach check points 
(see Listing 2). 

If the appropriate notification message 
doesn’t appear on schedule, our guards 
call the appropriate people. A number of 
jobs also send mail when they abend or 
run into various other problems. 

Our convention in MailHandler mes- 
sages is to load the text with the repeating 
quartets of keywords, tabs, text, and car- 
riage returns. The main reason for such 
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simple messages is that they were simple 
to create. Not only was a function to create 
these messages simple to write, but we 
can also create messages on an ad-hoc 
basis from within our normal mail client. 

When reviewing either the in-box or 
sent-mail folders of any computer, it’s 
easy to check sent and received mes- 
sages, and whether each message was 
formatted correctly. Finally, we could 
write a simple ParseText routine that 
would accept an array of keywords and 
fill it with the corresponding values be- 
fore returning it to the calling routine. 

From within a program, creating a 
message consists of setting the Text prop- 
erty of your message. About the only 
thing you have to watch out for here are 
carriage returns (Chr(13)). If you’re cre- 
ating amessage using the MAPI.VBX, don’t 
ever begin the text of a message with a 
carriage return. VB will simply refuse to 
send your mail if you do. 


RPC AND LICENSEE MANAGEMENT 


A more interesting example consists of re- 
questing another computer to run a pro- 
gram for you: sort ofa postal Remote Proce- 
dure Call. One of our systems required our 
users to enter daily status information and 
then click on a button to process this infor- 
mation against a table of 2 million records. 
This processing tied up the user’s com- 
puter for 10 minutes. We altered the pro- 
gram to send this message with the subject 
“Run Program—Do Update”: 


Program: P:\MASYSTEM\UPDATE. EXE 


Recognizing that the subject contained 
the keywords “Run Program,” MailHandler 
would call the RunProgram routine to 
process the message. 

The simplest version of the RunProgram 
routine parses the keyword “Program:” and 
runs the program named after the tab. We 
enhanced the program by adding a routine 
to prevent MailHandler from moving to the 
next piece of mail until the program that was 
started had run to completion. 

Not every process can use this facility 
due to the time lag between request and 
performance. Our mail clients can wait as 
long as 10 minutes to send mail to the 
server and, at the other end, our 
MailHandler computer can wait an addi- 
tional 10 minutes before retrieving its 
mail. If either computer is busy, the delay 
can be even longer. 

MailHandler won't respond to new mail 
until it has finished processing its current 
job. All these considerations mean that time- 
sensitive jobs can’t be naively implemented 
using Mail. In this case, the job would be 
done in time ifit finished before midnight, so 
it was a perfect candidate for MailHandler. 

It’s also important to recognize this 


store-and-forward process as a benefit. If 
the network is down, the mail client will 
hang on to the mail until it can be sent 
over the network. At the other end, if the 
receiving computer is down, the mail sys- 
tem will hang on to the mail until it can be 
sent. This fault tolerance ensures that the 
mail will get through. 

Passing the command-line parameters 
to the program required a more compli- 
cated format. Our LAN-based applications 
often needed to transfer data to the AS/400, 
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Mos’ FLEXIBLE 
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which was unable to handle ODBC access. 

We wanted to limit the number of com- 
puters we installed the upload-to-AS/400 
program on, so we installed it on a single 
computer along with MailHandler. Mail 
sent to this computer still uses the 
RunProgram message, but we enhanced 
the routine to handle a command-line 
keyword. The message: 


Program: S:\SOFTWARE\TRANSFER. EXE 
CommandLine: P:\TRANSFER\BINFILE.TTO 
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Sub DisplayAttachment (cntMail As Control, ingPos 
As Integer) ; 
Dim stzAttachment As String, stzDefaultDir As String 

Dim stzExecutable As String * 128 

Dim ingResult As Integer 

Dim obj As object 

Dim ingEndPos As Integer 

cntMail.MsgIndex = ingPos 

stzAttachment = cntMail.AttachmentPathName 

stzDefaultDir = "C:\" 

ingResult = FindExecutable%(stzAttachment, _ 
stzDefaultDir, stzExecutable) 

If ingResult > 32 Then 
-ingEndPos = InStr(stzExecutable, ".EXE") 


_MAPI_WORK 


ingResult = Shell(Left$(stzExecutable, ingEndPos + _ 
3) & " " & stzAttachment & Mid$(stzExecutable, _ 


stzAttachment & "." 
End If 
End Sub H 
Sub SetExcelCommand (stzCommandLine as string, _ 
stzDocument as string) © 
Dim obj As object | 
Set obj = CreateObject("Excel.Application.5") 
obj.workbooks.open stzDocument 
obj.Range("Command").value = stzCommandLine 
obj.activeworkbook.[Close] True 
obj.quit | 
Set obj = Nothing 
End Sub 
Sub SetWordCommand (stzCommandLine as string, _ 
stzDocument as string) | 
Dim obj As object 
Set obj = CreateObject("word.basic") 
obj.fileopen stzDocument 


ingEndPos + 4, 20), 1) 
Else 


obj.fileclose 1 
Set obj = Nothing 


MsgBox "Unable to find program to open" &_. End Sub 


obj.setdocumentvar "Command", stzCommandLine 


LISTING 3 All Set! SetExcel and SetWord provide a standard way to pass data to Word and Excel. It’s important to set the object variables 
to Nothing before ending the routines. If you don’t do this, both applications are prone not to give up their resources or, in 


Excel’s case, not shut down at all. 


A Brief Introduction to the MAPI Family 


The MAPI family consists of three sib- 
lings: Simple MAPI, Extended MAPI, 
and Common Messaging Calls (CMC). 
The MAPI.VBX rests on Simple MAPI, 
which has unfortunately become the 
family’s black sheep. CMC is the 
younger, more favored half-sister, 
while Extended MAPI is the more ca- 
pable big brother. 

MAPIis designed to allow Windows 
to do for electronic mail what it has 
already done for printing—remove 
device dependence. If you use MAPI 
calls in your program to implement 
electronic mail, your application 
should be able to work with any combi- 
nation of vendors’ address books, mes- 
sage stores, and transport services. Like 
printing, MAPIis a complete subsystem 
within Windows with a set of front-end 
interfaces for your application to use 
and back-end interfaces for e-mail ser- 
vices. In the same way that the printing 
subsystem makes plotters and printers 
look alike to your application, MAPI 
makes fax services and bulletin boards 
appear the same. Like the printing sub- 
system, the MAPI subsystem has its 
own spooler. MAPI also breaks e-mail 
down into four separate kinds of ser- 
vices—address books, message stores, 
transport services, and profile services 
(which allow users to specify which 
combination of services they require). 
MAPI allows application developers to 
work with any combination of MAPI- 
compliant service providers. 

MAPI was created by Microsoft in 
consultation with industry vendors as 
part of the Windows operating system 


and services. CMC was developed later, 
in conjunction with the X.400 API Asso- 
ciation. Because it is based on X.400 
specification, it’s a platform- and OS- 
independent specification. Microsoft’s 
recommendation is that you use Simple 
MAPI only if you have legacy Simple 
MAPI applications to support. 

CMC is designed to allow developers 
access to basic mail functions froma wide 
set of tools—from application macro lan- 
guages to C++. Unlike ODBC, MAPIhasno 
conformance levels other than the dis- 
tinction between the minimum level rep- 
resented by the 10 CMC calls and the full 
functionality of Extended MAPI. It is the 
developer’s responsibility when work- 
ing with Extended MAPI to determine 
what functionality is available from the e- 
mail services. 

From within Visual Basic, MAPI VBX 
represents the easiest access to the func- 
tions of CMC. Similarly, within Access 
and Excel it’s easy to use the SendObject 
action and SendMail method, respec- 
tively. The Word Resource Kit provides 
functions for using MAPI within Word, 
or you can use the workarounds sug- 
gested in the article. Microsoft may 
choose to implement the functionality 
of these high-level objects through any 
of the MAPI family without impact on 
your applications. However, in other 
environments you may have to choose 
between CMC and Extended MAPI calls. 

Microsoft distinguishes between 
three kinds of mail-enabled applica- 
tions. Mail-aware applications are those 
that make mail operations available as 
part of their feature set. The ability to 


route a Word document through sev- 
eral users is a typical example. These 
applications will probably find all their 
needs met with CMC. Mail-reliant ap- 
plications need mail to perform their 
functions, while workgroup applica- 
tions are, in many ways, high-level 
mail processors. These applications 
should probably look to Extended 
MAPI. The distinction often comes 
down to whether the application needs 
to read mail. If it does, more often 
than not it is going to require Ex- 
tended MAPI. 

In addition to being object oriented, 
Extended MAPI provides many features 
that CMC does not. Three of the more 
important are: 


e Access to the hierarchy of folders. 
CMC allows the developer to view only 
the contents of the user’s in-box. The 
developer cannot view, create, or de- 
lete other folders, or move messages 
between folders. 

e Search capabilities. The search capa- 
bilities within Extended MAPI allowthe 
developer to build complicated cross- 
folder searches and display the results 
of the searches in anew “search folder.” 
e Event notification. Extended MAPI 
lets applications request that MAPI 
notify them when certain events oc- 
cur, eliminating the need for polling. 


A similar initiative is the VIM (Ven- 
dor Independent Mail) specification 
developed by Borland, Lotus, Apple, 
and IBM. Many mail-service providers 
support both specifications.—P.V. 
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launches the transfer program pass- 
ing the name of the transfer specifica- 
tion file (BINFILE.TTO) on the com- 
mand line. Needless to say, the first 
version of this new routine worked 
well when a command line was speci- 
fied, but crashed when it got one of the 
old messages with no command-line 
parameter. 


ROAD WARRIOR SUPPORT 
While the RunProgram routine would 
handle a great many situations, we had to 


add a new routine to handle Microsoft 
Access. Perhaps your sales staff needs to 
request from the database information 
regarding sales to a customer, typically 
before visiting that customer. While we 
wrote an Access application to provide 
the information, it runs too slowly over 
dial-up links to be useful to salespeople 
on the road. A program to create and mail 
this message with the subject “Run Pro- 
gram—Get Sales Status” takes about 20 
minutes to write in VB, and less time in 
Access: 
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Program: MSACCESS.EXE 


Document: P: \MASYSTEM\ORDERS.MDB 
CommandLine: 145678 Wbrimley 
Macro: GetOrderInfo 


Here, the command-line data consists of 
the customer number and the e-mail ad- 
dress of the salesperson requesting the 
information. When a computer at corpo- 
rate headquarters running MailHandler re- 
ceives this mail, the RunProgram routine is 
called. RunProgram parses the message, 
starts Microsoft Access with the specified 
database, and uses Access’s /X command- 
line parameter to specify the macro to run. 
It willalso use the/C parameter to pass data 
to Access on the command line. 

The GetOrderInfo macro that the mes- 
sage requested to run is three lines long 
and consists of the actions: 


e SetWarnings, to turn off Access’s warn- 
ing messages. 

¢ SendObject, to create and mail the re- 
port as an Excel spreadsheet. 

© Quit, to exit Access after the job is run. 


The query that generates the report 
must be altered to parse the first word of 
the command line and use it as the crite- 
ria to select the customer: 


Left$(Command$(),Instr(Command$()," ")-1) 


The SendObject action must parse the 
second word in the command line to get 
the address of the salesperson to mail the 
report to: 


Mid$(Command$(),Instr(Command$()," ")+1) 


Your road warriors send their requests 
and get their answers by return e-mail. 
If several pieces of mail are to be sent 
and processed in order, be careful. While 
MAPIcan sort the mailin order by timesent, 
the precision of the time can’t be any finer 
than to the minute. As a result, if two mes- 
sages are sent in the same minute, their 
processing order is not guaranteed. When 
we needed to send more than one piece of 
mail and needed the messages to be pro- 
cessed ina specific order, we had to ensure 
that they were sent at least a minute apart. 
In Word, you specify the startup macro 
with the /M switch. In Excel, you can specify 
only one routine to be run when a work- 
book is opened. For workbooks that have 
several different routines, an Auto_Start 
routine must parse the command-line infor- 
mation and call the appropriate routine. 
Neither Word nor Excel support the 
CommandO function from Access and Vi- 
sual Basic, so datacannot be passed through 
command-line parameters. The simplest 
workaround is to use OLE Automation in 
the RunProgram routine of MailHandler to 
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set a cell called Command in the Excel 
worksheet to the passed values. In Word, 
setting a document variable accomplishes 
the same task (see Listing 3). 

The RunProgram routine checks Ac- 
cess, Excel, and Word as the specified 
program to format their command lines 
correctly and set the passed data. It might 
have been better practice to create sepa- 
rate routines with their own keywords 
and message formats. 

Creating return mail in both Excel and 
Access is simple. The SendMail method in 
Excel and the SendMail Action in Access 
are the single commands required to mail 
workbooks, forms, reports, or tables. 

In Word, however, sending mail is more 
difficult. One solution is to use the Word 
Resource Kit, which includes a Word DLL 
with the necessary MAPI routines. The 
Word Resource Kit is available in The 
Word Developer Kit, Second Edition, Ver- 
sion 6.0 from Microsoft Press (SBN 1- 
55615-681-2) and in the Microsoft Office 
Developer’s Kit. As a workaround, you 
can create a Word macro using Word’s 
MailMerge commands. 

While the required Word macrois only 
a few lines long, before you can use it you 
must create a Word data document con- 
taining the Address! field. The Word 
MailMerge Wizard lets you do this: create 
a data document called MAILDUM.DOC. 
Put a copy on each computer running 
MailHandler. At mail time, the macro 
opens MAILDUM.DOC and changes the 
Address] field to the e-mail address ofthe 
person to be mailed to. It then closes 
MAILDUM and mails the document: 


Sub MailIt(address$, subjecttext$) 


FileOpen .Name = _ 
"c:\msoffice\winword\maildum.doc" 
NextCell 


Insert address$ 
FileClose 1 
MailMergeOpenDataSource 
.Name = "MailDum.doc" 
MailMerge .Destination = 2, 
.MailSubject = subjecttext$, 
.MailMerge, 
.MailAddress = "Address1" 
End Sub 


MailSubject can be set to any string you 
like and will be used as the subject line of 
your mail message. Using a menu selection 
from Word’s General Options menu, youcan 
choose to have the document sent as the 
body of your message or as an attachment. 


THE USER INTERFACE 

Having gone this far, the next step was to 
move out of merely batch processing and 
into an interactive world. We were al- 
ready mailing various Access reports to 
our users as Excel spreadsheets or at- 


taching Word documents to our mail. 

However, our users were having diffi- 
culty finding and working with this output 
when their in-boxes got full. Putting a 
front end on MailHandler turned out to be 
relatively easy and allowed our users to 
find and process their computer-gener- 
ated mail more easily. 

The first step was to enhance the 
Form_Load procedure to accept an- 
other parameter to display the user 
interface: 
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Sub Form_Load 

If command() = "/I" 
frmUI.Show 

Elself command() = "/T" Then 

" etc. 

End Sub 


The second step was to add a line to 
the MSMAIL.INI file to put “Process Mail” 
on the Tools menu of the user’s Mail 
client. When selected, this choice calls 
MailHandler with the /I parameter: 


SQL-SOMBRERO ann 


SOL-Sombrero/VBX 


The Complete V. 
DB-Library” for SQL Server™ 


SQL-Sombrero/VBX: 


SQL-Sombrero/VBX for DB-Library component will 
allow you to do just that. The SQL-Sombrero/ VBX is a 
Visual Basic® Extension that provides the direct interface 
to use DB-Library functions without using C or C++. 

Direct access to the SYBASE®/Microsoft® 
DB-Library functions: SQL Sombrero/ VBX for DB-Library 
allows direct access to SYBASE/Microsoft DB-Library 
functions from any product that uses Visual Basic 
VBX files. 

Direct access to DB-Library from Visual Basic! In 
conjunction with Visual Basic you can have total control 
over accessing all Microsoft and SYBASE SQL Server and 
Gateways, including the SYBASE®/Micro Decisionware 
Inc. Database Gateways. It can also be used to replace 
the use of ODBC and VBSQL when using SQL-Sombrero/ 
VBX or SQL-Sombrero/OLE for DB-Library. 


SQL-Sombrero/VBX for DB-Library features: 


> contains all of the DB-Library functionality 
(over 120 functions) 


> includes Windows™ on-line help 
> gives access to all DB-Library Bulk-Copy functions 


> works with Microsoft and SYBASE SQL Server 
(System 10 also) 


SOMBRERO 
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PWF=3.0;Mail;&Process Mail...;13;_ 
APPEXEC.DLL;C:\MAILHAND.EXE /1;;_ 
Process workflow mail;_ 
MSMAIL.HLP;0000 


If the user needs to interactively pro- 
cess received mail, you should remove the 
line in the MAIL.INI file that causes mail to 
process automatically (see Figure 3). 

With this housekeeping out of the way, 
we began development on the workflow 
front end to MailHandler. Previously, the 
system retrieved all unread mail and pro- 
cessed it immediately. The workflow 
screen would have to retrieve all the mail 
and process it on request. To handle this, 


2 


Microsoft Mail 


the workflow screen retrieved the unread 
mail with interesting keywords and loaded 
the subject line to astandard grid control. 
Along with the subject information, the 
position of the message in the mail queue 
was stored in the grid. A double click on any 
cellonthegrid calls thestandard ProcessMail 
routine, passing the MAILMESSAGE control 
and the position of the selected message in 
the queue as usual (see Figure 4). 
Members of the systems group in 
my organization were the first users of 
the screen. When mail needed to be 
reprocessed, or processed out of or- 
der, the workflow screen made the job 


much easier. 
=I] 


File Edit View (EI) Window Help 


Compose Note 


Reply to All 


Address Book... 
Personal Groups... 


Ctril+N 


g, ees a 
Delete Piewious Mex 


Inalasse... 10/5/95 10:53AM 


i Options... 
Change Password... 
Backup... 


© Sent mail 
© Wastebasket 


ask Fore... 10/6/05 9:54AM 

b Users - ... 11/7/05 1:55PM 

MACHIN... 11/9/95 8:11AM 
11/9/95 10:08AM 


. b Users - ... 11/9/95 5:09PM 


a 
@ EdGooyers Physical Inventory 1... 11/10/95 5:33PM 


& To: Lox A... Watcom Server 
finished 


8 Download... Yee 


11/13/95 8:37AM 
11/13/95 10:06AM 


/2 Mail Handler Schedule Notification 11/13/05 10:15AM 
@ Mail Handler Schedule Notification 11/13/95 10:15AM 


Create new message 


[12 messages: 4 unread | 


FIGURE 3 The Process for Processing Mail. A single line in the user’s MSMAILINI file 
allows the user to start an interactive session with MailHandler. Clicking on 
“Process Mail” starts MailHandler with the /I option, causing it to display a list of all the 


mail it finds interesting. 


WorkFlow Mail Management 


(= Junread | 


ages 
J 


FIGURE 4 Junk Mail? The workflow screen allows the user to review his or her computer- 
generated mail and process it. In addition to processing the message, the user 
can delete the mail, read it, forward it, and add annotations. 


The next application was for our order- 
processing system. When an order requires 
financial approval, a mail message would 
be sent from the order-entry application to 
our finance manager. Once received, the 
mail message opens the application dis- 
playing the sales order whose order num- 
ber was passed on the command line: 


Program: Ordentry.Exe 
CommandLine: 17406 


Weaddeda “Display Attachment” key- 
word to the system to allow our users to 
review e-mailed reports without having 
to search them out in their mailboxes, 
fulfilling the original objective in adding 
the interactive processing. 

Now that you’ve started sending mail 
to particular users, it’s important that 
you do not use their e-mail addresses as 
the “To:” line of the message. If you do, 
each time someone changes jobs you will 
have to rewrite your code. 

Instead, set up recipient lists named for 
thejob that is to be done and direct the mail 
to the list name. While most lists will have 
only one member, this practice allows you 
to have mail sent to multiple users where 
necessary. As people change jobs and jobs 
are reassigned, you can use your mail 
system’s administration facility to change 
the person who belongs to the job. 

At the very least this saves you from 
having to develop the facility yourself. 
The only documentation that must be 
maintained is a list of which job streams 
are associated with which recipient lists. 

This is only a small peek at what mail 
can do for you. Weare starting to keep our 
documentation and company guidelines 
in Windows help files. At the top of each 
help screen is a button that allows the 
user to mail comments, corrections, and 
additions to the help file’s manager. 

A database of reviewers and inter- 
ested parties for each help file helps 
keep track of who should be notified (by 
mail, of course) when the file is updated. 
The interactive screen allows the respon- 
sible person to manage and track these 
requests. 

I keep a schedule of what jobs are to 
have been run at what times over the 
course of the day. MailHandler writes toa 
log file every time it performs an activity. 

Periodically the system runs a job 
that checks to see if some scheduled job 
hasn’t run on time and mails a “Notify” 
message to the responsible person 
(note: many mail systems will automati- 
cally forward the mail to a delegate if a 
person is away). Also, we can run a 
monthly report comparing MailHandler 
recorded activity against the schedule. 
For a lot of problems, the answer is in 
the mail. x! 
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esign buttons 

that are unique 

to your application. 
ButtonMaker gives you the 
| ability to create buttons of 
virtually any shape or size. 


Picture-Perfect Buttons 


FarPoint’s exclusive Button 
Designer provides you with 
complete control over creating 
your buttons at design time. 
Each button can be assigned 
e” any number of points or seg- 
ments. You have the ability to 
give the segments different 
shapes and lengths or to load 
a predesigned template. 


Multiple cells can be created 
within each button, allowing 
you to set background and 
foreground color, text, fonts, 
and text orientation for each portion of your 
button. You can also insert pictures within each 
cell, including 256-color bitmaps. 


To find out what ButtonMaker 
can do for you, call our sales 
department at (800) 645-5913 
or (919) 460-4551 to request a 
free demo disk. 


VISUAL 
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SERIES 
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Hot Spots 


Each cell within your button can be defined 
as a hot spot. Hot spots can be individually 
recognized through the MouseOverCell 
property, allowing one button to perform 
multiple commands. ButtonMaker’s hot 
spots let you assign numerous 
functions to a single control. 


Prints the Selected Text ) 


Help is a Balloon Away [23 &"| 

Make your interface more user-friendly by using 
FarPoint’s Balloon control, which is included free 
with ButtonMaker. Balloons display a help bub- 
ble when the mouse pointer is positioned over a 
) control. You can choose any of 
the following shapes: round, 
square, ellipse, and cloud. 


ButtonMaker, part 


a VBX, a 16- and 
32-bit OLE control, and a 16- 
and 32-bit DLL. 


ButtonMaker can be pur- 
chased directly from FarPoint 
Technologies, Inc., as well as a 
number of software resellers. 
ButtonMaker is royalty free 
and comes with a 30-day 
money-back guarantee. * 


Far 


Technologies 


Phone, Calculator, 
and Remote were 
created entirely using 


133 Southcenter Court, BultonMaker: 


Suite 1000 Morrisville, NC 27560 
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Creating OLE Servers 


Using VB4 to create an OLE server 
is easy, if you follow a few tips and 
tricks. 


by Deborah Kurata 


ne of the exciting things you can do with classes is 
create OLE servers. OLE servers expose your 
application’s objects and their properties and methods 
to other applications. You can develop a centralized inventory- 
control OLE server, for example, and any application that needs 
to adjust inventory can simply use your precompiled compo- 
nent. Or you can write a pricing-model server, or a to-do-list 
server, or an API wrapper, or a standard login screen, or ... the 
possibilities are endless! 

Using Visual Basic 4.0 to create an OLE server is easy, if you 
know a few tips and tricks. Once you’ve created the OLE server, 
any application that supports OLE Automation (called an OLE 
client application) can use it, including applications developed 
in Visual Basic 3.0 or 4.0, Visual C++, Excel, and Access. 


TIP 1: DESIGN THE OLE SERVER 

This tip seems obvious enough, but is frequently overlooked or 
abbreviated. The trick to a good design is first to clearly identify 
the objects your server will provide and the properties and 
methods of those objects. An easy way to do this is with CRC 
cards, which are simply index cards used to document your 
object design (see Programming with Class, “Designing Objects 
for VB4,” by Kathleen Dollard-Joeris, in the December 1995 issue 
of VBPJ). 

After you have identified the objects, you need to establish 
the relationships between the objects. This involves creating an 
object hierarchy for an inventory-control OLE server (see Figure 
1). Be sure to have one object at the top of the hierarchy. If you 
have more than one at the top, you will need to define an 
additional object that will reside above the other objects at the 


Deborah Kurata is principal consultant and cofounder of InStep 
Technologies, a consulting group that designs and develops object- 
oriented Microsoft Windows applications. ——————————_+ 


She is the author of Doing Objects in | ====3 Doing Objects 
Microsoft Visual Basic 4.0, published by in Microsoft 
ZiffDavis Press, which focuses on a prag- | jx Visual Basic4.0 


matic approach to object-oriented design 
and development of Visual Basic applica- 
tions. Reach her at InStep Technologies, 
5424 Sunol Blvd. #10-229, Pleasanton, CA 
94566; or on CompuServe at 72157,475. 
Youcan also find her leading the Beginner’s 
Corner section of the VBPJ Forum on 
CompuServe. 
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top of the hierarchy. This top-level object will own the other 
objects in the application. If there is more than one top-level 
object, it is not clear which object owns the others. 

To keep your code simple, keep the hierarchy relatively flat. 
Don’t add too many levels to your design. Because Visual Basic 
4.0 supports containment (“has a”) relationships instead of 
inheritance (“is a”) relationships, each higher-level object must 
expose the lower-level objects. If the hierarchy gets over three 
or four levels high, managing the composition relationships 
becomes much more difficult. 

Another trick to OLE server design is good naming conven- 
tions. Because the OLE server can be used from any other 
application that supports OLE Automation (including the execu- 
tives’ Excel spreadsheets), you want to give the properties and 
methods of the OLE server good names. In an inventory-control 
OLE server, for example, instead of a property with a techie 
name such as gsInvProdName, the property could simply be 
ProductName. Instead of a method called iAddInv, the method 
could simply be AddInventory. 


TIP 2: SEPARATE FORM AND FUNCTION 


During the design stage, think carefully about the functionality 
of your OLE server separate from any user interface. In most 
cases, your OLE server does not need its own user interface. 
Rather, a client application can provide the interface and the 
OLE server can provide the functionality required for that 
interface. 

For example, in developing aninventory-control OLE server, 
you'll provide methods for incrementing inventory when prod- 
ucts are received, decrementing inventory when products are 
sold, and adjusting inventory when physical counts are taken. 
The OLE server could provide screens for each of these func- 
tions, but a better implementation allows the OLE client appli- 
cations to control the user interface. You can then easily 
change, localize, port, or replace the user interface without 
affecting the OLE server. Likewise, you can modify the busi- 
ness rules in the OLE server without affecting the client 
application’s user interface. 


FIGURE | Drawing the Object Hierarchy. The object hierarchy 
depicts the containment, or composition, eas 


In case, the inventory “has a” set of items. 
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This is even more important if you are planning to provide 
the OLE server as aremote automation server, a server installed 
onasystem separate from the OLE client applications. If the OLE 
server does have a user interface, it will appear to the system it 
is installed on. So if your Receive Inventory form is part of the 
OLE server, the form will appear on the remote server computer 
instead of the local computer requesting the OLE server. 


TIP 3: PROTOTYPE THE SERVER 


Once the design of the server is complete, the next logical (and 
fun) step is to prototype the server. This step involves actually 
writing the outline of the code for the server. You can create the 
class modules, add the Property procedures, and define the 
subroutines and functions for the methods. Because this is a 
prototype, you don’t need to develop any real code to access the 
data or process information. You can simply hard-code values 
in the Initialize events and add comments where the real code 
will need to go. 

For the inventory-control OLE server, an Item class will track 
the information required for each item in inventory. As with 
every class, begin the code with a header, meeting the coding 
standards you follow: 


" Class Name: CItem 

" Author: Deborah Kurata, InStep 
Technologies 

" Date: December 10, 1995 

' Description: Track inventory item 

" Revisions: 

* NOTE: 


This is currently a prototype! 


The Declarations section of the class contains the definition 
of the properties of this class. Define these properties to be 
private and local to this class. They will be exposed publicly 
through the Property procedures: 


' Private data members 

Private m_]ProductID As Long 
Private m_sProductName As String 
Private m_sProductNumber As String 
Private m_iQuantity As Integer 


" Removes inventory from the system 

' This is used when inventory is sold, 

' damaged, or adjusted 

" Parameters: 

" sInvitem Product Number of the 

item 

" 7NumRemoved Number of the 

: product removed from 

! inventory 

" Returns: 

' jTotal Total number in 

Y inventory 

Public Function _ 
Removelnventory(sInvItem As _ 
String, iNumRemoved As Integer) As _ 
Integer 

Dim iCurrentTotal 


" Retrieve the current inventory 
" count from the collection 


ies 


Private Sub Class_Initialize() 
" Create the collection of inventory 
" items 
CollectProducts 

End Sub 


‘ Fills the collection with the products 
Private Sub CollectProducts() 
' This is the prototype code 
" to create the data in the collection 
" Normally this information would 
' exist in a database 
Dim Item As New ClItem 


Item.ProductID = "1" 
Item.ProductNumber = "WD-123" 
Item.ProductName = "Widgets" 
Item.Quantity = 16 


' Add this one to the collection 

' Using the product number 

"as the key 

m_colItems.Add Item, _ 
Item.ProductNumber 


" Clear the reference 
Set Item = Nothing 


" Set another one 
Item.ProductID = "2" 
Item.ProductNumber = "GG-123" 
Item.ProductName = "Gagets" 
Item.Quantity = 120 


' Add this one to the collection 

' Using the product number 

"as the key 

m_colItems.Add Item, _ 
Item.ProductNumber 


End Sub 
een =a] 
Initialize It. Notice the trick with the Set Item = Nothing 

statement in the CollectProducts routine within the 


Initialize event. This clears the object reference in preparation for 
creating another object. Without this statement, the new assignments 


would simply be updating the prior object. 


iCurrentTotal = _ 
Me.Item(sInvItem).Quantity 


' Perform the subtraction 
iCurrentTotal = iCurrentTotal - _ 
iNumRemoved 


Code here should ensure the total 
number in inventory is never < 0 


Code here could also check the 
reorder point and automatically 
reorder when an order point is 
reached 


Update the collection 
Me.Item(sInvItem).Quantity = _ 
iCurrentTotal 


" Return the total amount 
RemovelInventory = iCurrentTotal 


End Function 


LISTING | Take Them Away. The Removelnventory method of the inventory-control OLE server retrieves the current inventory count 
for the defined inventory item, decrements the total, updates the inventory count, and returns the current number of the item. 
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The prototype of the Property procedures simply assigns | Public Property Let ProductID(1ID As Long) 
and retrieves the value of the private data members. In the real m_1ProductID = 11D 
application, you would add code to these to validate the data | End Property 
before assigning the value and to format the data before retriev- | Public Property Get ProductID( ) As Long 
ing the value. A trick for making these easier to find later is to put ProductID = m_1ProductID 
them in alphabetical order: End Property 


message would be 


displayed to the user 


" here 
' Form Name: frmInventory " With a more detailed 
' Author: Deborah Kurata, InStep "message printed to a 
: Technologies " log file 
" Date: December 10, 1995 MsgBox Err.Description 
" Description: Inventory form. End If 
" This is a little test form for the OLE 
" server and NOT a good design for an " Display the revised 
" inventory form! ' inventory amount on the 
y " screen 
" Revisions: txtTotal.Text = iTotal 
Option Explicit Case SELL 


Product number for the 
inventory item 

NOTE: combo's are O based, 
collections are 1 based 


" Private member variables 
Private m_Inventory As CInventory 


" Constants for the command butons sProductNumber = _ 
Const iCLOSE = 0 m_Inventory.Item_ 
Const iRECEIVE = 1 (cboItems.ListIndex + 1).ProductNumber 


Const iSELL = 2 
" Remove the defined amount 


Private Sub cboItems_Click() ' from the inventory 
' If the user selects an item iTotal = m_Inventory.RemovelInventory_ 
" clear the number received (sProductNumber, Val(txtReceived.Text)) 
txtReceived.Text = "" If Err.Number <> 0 Then 
"A more friendly error 
" Set the total in inventory as " message would be 
' appropriate " displayed to the user 
If cboItems.ListIndex <> -1 Then " here 
txtTotal.Text = m_Inventory.Item_ " With a more detailed 
(cbhoItems.ListIndex + 1).Quantity " message printed to a 
End If " log file 
MsgBox Err.Description 
" Ensure the button is disabled End If 
"until a quantity is entered 
cmdInventory(iRECEIVE).Enabled = False " Display the revised 
cmdInventory(iSELL).Enabled = False ‘inventory amount on the 
End Sub " screen 
txtTotal.Text = iTotal 
Private Sub cmdInventory_Click(Index As Integer) End Select 
Dim iTotal As Integer End Sub 
Dim sProductNumber As String 
Private Sub Form_Load() 
Select Case Index Dim colItems As New Collection 
Dim 1Count As Long 
Case iCLOSE 
Unload Me " Create only one instance of the 
" inventory class 
Case iRECEIVE Set m_Inventory = New CInventory 
" Product number for the If Err.Number <> 0 Then 
' inventory item : "A more friendly error message 
" NOTE: combo's are 0 based, " would be displayed to the user 
" collections are 1 based " here 
sProductNumber = _ " With a more detailed message 
m_Inventory.Item_ " printed to a log file 
(cboItems.ListIndex + 1).ProductNumber MsgBox Err.Description 
Unload Me 
" Add the defined amount to GoTo EXIT_Form_Load 
" the inventory End If 
jTotal = m_Inventory.AddInventory_ 
(sProductNumber, Val(txtReceived.Text)) " Fill the combo box with values 
If Err.Number <> 0 Then For 1Count = 1 To m_Inventory.Count 
eopemone i nvendily/encon CONTINUED ON PAGE 84. 


ListING 3 Tracking Your Inventory. The code for this inventory-control test form would create the top-most level object in your object 
hierarchy, then exercise the properties and methods provided by the OLE server classes. The majority of this code responds 
to the Click event of the command buttons on the form. 
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Public Property Let ProductName(sName As String) 
m_sProductName sName 

End Property 

Public Property Get ProductName( ) As String 
ProductName = m_sProductName 

End Property 


Public Property Let ProductNumber(sNumber As String) 
m_sProductNumber = sNumber 
End Property 


CONTINUED FROM PAGE 82. 


With m_Inventory.Item(1Count) 
cboItems.AddItem .ProductNumber & _ 
Space(5) & .ProductName 
End With 
Next 1Count 


EXIT_Form_Load: 
End Sub 


Private Sub Form_Unload(Cancel As Integer) 
" Clear the instance 
Set m_Inventory = Nothing 

End Sub 


Private Sub txtReceived_Change() 

' If there is an amount entered and 

" the command button is disabled, 

‘enable it 

If txtReceived.Text <> "" And _ 
cmdInventory(iRECEIVE).Enabled _ 


Fa 


WITH CLASS 


Public Property Get ProductNumber( ) As String 
ProductNumber = m_sProductNumber 
End Property 


Public Property Let Quantity(iQuantity As Integer) 
m_iQuantity 

End Property 

Public Property Get Quantity( ) As Integer 
Quantity = m_iQuantity 

End Property 


jQuantity 


= False Then | 
cmdInventory(iRECEIVE).Enabled _ 
= True 
cmdInventory(iSELL).Enabled _ 
= True 
End If 
End Sub 


Private Sub _ 
txtReceived_KeyPress(KeyAscii - 

As Integer) 

If (Chr$(KeyAscii) <> vbBack) And _ 
(Not IsNumeric(Chr$(KeyAscii))) _ 
Then 
Beep 
KeyAscii = 0 

End If 

End Sub 
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sary tools to create a graphically rich interactive 
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our 30-day Free Trial Server available at 
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Custom Windows Menu: 


The Inventory class owns the collection 
ofinventory items. Define this containment 
relationship in the code by declaring the 
collection within the Inventory class: 


" Class Name: CInventory 

" Author: Deborah Kurata, InStep 
Technologies 

" Date: December 10, 1995 


Description: Track inventory 
Revisions: 

" NOTE: 

' This is currently a prototype! 


Option Explicit 


' Private data members 
Private m_colltems As New Collection 


The AddInventory method retrieves 
the current inventory count for the de- 
fined inventory item, increments the to- 
tal, updates the inventory count, and 
returns the current number of the item: 


' Add inventory when product is 

" received 

' Parameters: 

' sInvitem 

' of the item 

' iNumReceived Number of the 

" product received 

" Returns: 

' {Total 

" inventory 

Public Function AddInventory(sInvItem _ 
As String, iNumReceived As _ 
Integer) As Integer 

Dim iCurrentTotal 


Product Number 


Total number in 


" Retrieve the current inventory 

" count from the collection 

iCurrentTotal = _ 
Me.Item(sInvItem) .Quantity 


' Perform the addition 
iCurrentTotal = iCurrentTotal + _ 
iNumReceived 


' Update the collection 
Me. Item(sInvItem).Quantity = _ 
iCurrentTotal 


" Return the total amount 
AddInventory = iCurrentTotal 
End Function 


You could enhance the AddInventory 
code to ensure the amount in inventory 
does not exceed the storage capacity for 
that item. It could also generate receipt 
information, perform accounting trans- 
actions, and so on. 

Because the collection of inventory 
items is private to this class, other appli- 
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cations cannot access the methods or 
properties of the collection. To provide 
access to the method or property, you 
can develop wrappers. The Count Prop- 
erty procedure in this class is simply a 
wrapper for the Count property of the 
collection and provides the current num- 
ber of inventory items in the collection: 


' Wrapper for collection count 
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Public Property Get Count() As Integer 
Count = m_collitems.Count 
End Property 


The Item method of this class is a 
wrapper for the Item method of the col- 
lection. It provides access to the lower- 
level object. This provides the mecha- 
nism for other applications to referencea 
property of the lower-level object, in this 
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case the inventory item: 


" Wrapper for the collection 
" Parameters: 
" vIndex 


string to find by key 

numeric to find by 

position 

Public Function Item(ByVal vIndex As Variant) As CItem 
Set Item = m_collItems.Item(vIndex) 

End Function 


The Removelnventory method retrieves the current inven- 
tory count for the defined inventory item, decrements the 
total, updates the inventory count, and returns the current 


&@ Inventory 


FIGURE 2 Inventory Test Form. Test the operation of your OLE 
server with a simple, multipurpose form. This test form 


doesn’t need to be part of the actual user interface of your 
application. 
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number of the item (see Listing 1). You could add code to this 
method to ensure the inventory does not drop below zero for 
an item or to automatically define a back order. In addition, 
this could check a predefined reorder point for an item and 
automatically generate an order if the inventory count drops 
below the defined amount. 

The Initialize event for the class would normally fill the 
collection of items from a database. For the prototype, this 
information is hard-coded into the CollectProducts routine 
(see Listing 2). Notice the trick with the Set Item = Nothing 
statement shown between the two assignments. This clears 
the object reference in preparation for creating another ob- 
ject. Without this statement, the new assignments would sim- 
ply be updating the prior object. The collection would then 
contain multiple references to the same object. (Try this and 
then display the ProductID of each item in the collection. They 
will all be the same!) 

Finally, don’t forget to add that standard module with a Sub 
Main routine. This routine does not have to contain any code 
(the prototype didn’t need anything here), but you need to 
define the Sub Main so the OLE server will start up. 


OLE SERVERS EXPOSE YOUR APPLICATION’S 
OBJECTS AND THEIR PROPERTIES 


AND METHODS TO OTHER APPLICATIONS. 
i 


TIP 4: DEVELOP A STANDALONE APPLICATION 

Once you have the prototype code in place, you will want to 
run your OLE server. But an OLE server serves up objects, so 
unless something is requesting objects, the server doesn’t 
appear to do anything. You need to write an OLE client appli- 
cation that will create objects from your OLE server. 

However, testing and debugging an OLE server is a lot 
harder than testing and debugging a normal standalone appli- 
cation. The trick here is to perform the first set of tests on the 
OLE server as if it were a normal standalone application. 

To do this, simply add a form to the application that will act 
as the client for the server. Make this form the startup form for 
this application. For the inventory-control OLE server, I added 
a simple data-entry form (see Figure 2). It is often easier to test 
the server by providing access to all server functionality from 
one form. This test form need not be part of the actual user 
interface of your application. 

The code for this inventory-control test form would create 
the top-most level object in your object hierarchy, then exer- 
cise the properties and methods provided by the OLE server 
classes (see Listing 3). 

One of the benefits of developing a prototype and testing it 
in this manner is that you will find out, after only a few hours, 
if your design will provide the results you need. You will also 
learn about some of the rules of creating classes and accessing 
OLE servers. For example, you can’t pass user-defined types 
(UDTs) as parameters to a method in a class module and you 
can’t return a UDT from a method of a class module. 


TIP 5: MAKE THE APPLICATION AN OLE SERVER 


When you are confident of the basic operation of your classes, 
you'll want to make the application into a real OLE server. To 
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do this, first remove the test form from the project and then set 
the Public property on each class that will expose objects to 
True. The tricky part here is to be sure to set all exposed 
contained classes to Public as well. So if you expose a lower- 
level object, the class for that lower-level object needs to have 
the Public property set to True as well. For example, in the 
inventory-control OLE server, the Item object is exposed 
through the Item method of the Inventory class, so the Item 
class must have the Public property set to True. 

If you don’t want any application creating objects from the 
lower-level contained classes, simply set the Instancing prop- 
erty of the lower-level classes to None. This will prevent any 
other application from creating objects from these lower-level 
classes. However, be sure to set the Instancing property of the 
top-most class to Creatable SingleUse or Creatable MultiUse. 
Otherwise the form will not be able to create any objects from 
your server. 

After you’ve set the correct Public and Instancing proper- 
ties for your classes, you can use the Make EXE File command 
to make an executable. This executable is your OLE server. 
Note that because this executable is a Visual Basic applica- 
tion, it still needs all of the associated DLLs such as 
VB40016.DLL or VB40032.DLL. Keep this in mind when you 
attempt to install this OLE server on another computer. The 
trick to installing the components is to use the SetupWizard 
to install your OLE server and in Step 6, to set the “Install as 
OLE Automation shared component” deployment model. This 
will ensure all correct files are located, compressed, and 
copied to the diskette, then installed correctly on another 
system. 

Once you've created the EXE, you can use the Compatible 
OLE Server text box in the Project tab of the Options dialog box 
to set this EXE as a Compatible OLE Server. This will allow you 
to make changes to the server later without affecting the 
reference to the server. I’ll discuss this in more detail in Tip 6. 

If your application is ultimately going to be an OLE DLL 
instead of an EXE, you may want to follow this process to make 
it an EXE first. After testing the EXE, you can remake the 
application into an OLE DLL. 


TIP 6: TEST, TEST, TEST 

Now that you have a prototype of your OLE server, you can test 
it in all environments where it will ultimately be used. Will it be 
used from VB4, VB3, or Excel? If so, try all three to ensure the 
server works appropriately. Will it be used under Windows 3.1, 
Windows 95, or Windows NT? Again, try the server in each 
anticipated environment. 

So how do you test the server? The easiest approach is to 
create a new project and add the form described in Tip 4 (see 
Figure 2). Before this test OLE client application will run 
successfully, you need to define where it will find the OLE 
server. Do this using the References option in the Tools 
menu. You can select the OLE server from the list of available 
references. 

You can then run this OLE client application. The OLE 
server will be accessed appropriately. Notice that when you 
run the OLE server, it will appear in your system’s task list. This 
is because the OLE server runs in its own separate task. To 
have the server run in the same process as the OLE client 
application, remake the OLE server using the Make OLE DLL 
command. 

Now you are ready to add the real code to the OLE server and 
repeat these last three tips for running and debugging the 
server. Whether you're building an OLE EXE or OLE DLL, these 
tips and tricks should serve you well. XI 
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Exploit Jet SQL 


Sure you can keep using DAO. But 
you're better off with Jet SQL— 
once you get the hang of it. 


by Andrew J. Brust 


et’s version of SQL strays far afield from “standard” SQL 
in places, and I’ve found that few people take the time to 
master Jet SQL. Its annoying quirks still blindside VB 
programmers, while its useful extensions go unexplored. Most 
of us would rather write a query in a familiar SQL dialect, then 
tweak it until Jet stops tossing error messages at us. Eventually 
we'll get that inner join syntax right. Right? 

Still, you ought to learn Jet SQL. That time you spend debug- 
ging queries, or designing them visually in Access and copying 
the generated SQL, could be better spent doing real program- 
ming. And what about upsizing? You may need to convert your 
Jet SQL queries to your server’s SQL to implement passthrough 
queries. If you don’t remember exactly what that strange Jet SQL 
meant, your translation task becomes even more arduous. 
Further, for certain data definition tasks, such as creating and 
maintaining tables and indexes, SQL can provide a more effi- 
cient and terse coding vehicle than DAO provides. Basically, 
whether you're using VB3 or VB4, 16- or 32-bit, getting a firm grip 
on Jet’s SQL pays off. 

If you now know standard SQL pretty well, adding Jet SQL’s 
unique aspects to your repertoire doesn’t represent an over- 
whelming learning curve. For example, the GROUP BY, HAVING, 
and ORDER BY clauses, and subqueries in general, work in the 
same manner either way—unlike the WITH OWNERACCESS 
OPTION, PARAMETERS, TRANSFORM, and PIVOT clauses, which 
bear discussion. 

In addition, some of Jet’s standard SQL features get 
underutilized because users haven’t ventured beyond the 
procedural DAO code they already know. So we should also 
take a look at the SQL Data Definition Language (DDL) re- 
served words CREATE, DROP, and ALTER. These provide a 
great way to create and modify the structure of tables, in- 
dexes, and referential integrity relationships. They can often 
perform these tasks with much less code than you'd need to 
create and define TableDef, Field, and Index objects and 
modify their corresponding collections. 

For the sake of clarity I'll present all SQL commands and 
keywords in CAPS, although Jet’s SQL interpreter doesn’t care 
about case. Also, I’ve terminated all SQL queries with a semico- 


Andrew J. Brust is president of Progressive Systems Consulting Inc., 
a New York City-based firm specializing in the development of, and 
developer training in, client/server and other custom business 
applications.Reach Andrew on the Internet at abrust@progsys.com 
or on CompuServe at 70274, 1746. 


lon, in keeping with the formal, preferred syntax, although Jet 
SQL doesn’t care about this either. 

Irecommend starting your study of Jet SQL’s unique outlook 
on life with its most prominent syntax deviation, the JOIN 
clause. Most SQL dialects (including SQLServer’s Transact SQL) 
make you express joins as logical expressions in a query’s 
WHERE clause. But Jet allows for a JOIN subclause in the query’s 
FROM list. A SQL Server inner join query: 


SELECT tblCustomers.*, tblOrders.* 

FROM tbiCustomers, tblOrders 

WHERE tblCustomers.iCustId = 
tbl0Orders.iCustId 


becomes: 


SELECT tbiCustomers.*, tblOrders.* 

FROM tb1Customers INNER JOIN tblOrders 

ON tbiCustomers.iCustId = 
tblOrders.iCustId; 


in Jet SQL. You can use similar syntax for outer joins. Just 
substitute LEFT JOIN or RIGHT JOIN in place of INNER JOIN. Note 
that in certain cases you can nest JOIN clauses in Jet SQL (for 
example, table 1 inner-joins to table 2, which inner-joins to table 
3). By the way, Jet does allow you to express inner joins in the 
WHERE clause as you would in standard SQL, but the INNER 
JOIN syntax is preferred. Outer joins must be expressed with the 
LEFT JOIN or RIGHT JOIN syntax. Interestingly, Jet SQL’s JOIN 
syntaxis close to that of ANSI-92 SQL, although it seems different 
from most widely used SQL dialects. 


SELECTIVE EVOLUTION 

Jet’s SELECT command also deviates from garden variety SQLs. 
Look at the square bracketed components in the schematic 
syntax: 


SELECT [predicate] { * | table.* | 
[table.]fieldl [, [table.]field2.[, 
recat 

CAS aliasl [, alias2 [, 

FROM tableexpression [, 
externaldatabase] 

(WHERE... J] 

[GROUP BY... ] 

[HAVING... ] 

[ORDER BY... ] 

CWITH OWNERACCESS OPTION] 


teed] 
«+-] CIN 


Our first component, the predicate, defines the records in 
your query, if any, that will be filtered out of the result set that 
Jet gives back to you. Jet predicates consist of ALL, DISTINCT, 
DISTINCTROW, and TOP n [PERCENT]. ALL returns all records 
that meet the criteria outlined in the rest of your query. It is 
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implied—supplying the ALL predicate is like supplying no predi- 
cate at all. 

Distinguishing between the next two predicate elements, 
DISTINCT and DISTINCTROW, has confused me more than any 
other element of Jet SQL. For example, take a simple database 
consisting of tables tb|Customers and tblOrders, with this struc- 
ture and (very carefully chosen) data: 


tblCustomers: 
serena EA ST 
iCustld cFirstName cLastName 
RE ee ee 
1 Harry Smith 
2 Harry Jones 
tblOrders: 
ann 
iCustld iOrderld iAmount Quarter 
pase Son eke 
1 | 50 Q195 
1 2 50 Q295 
1 3 5 Q295 
2 1 44 Q194 
2 2 55 Q395 


Now make three queries and consider their result sets: 


SELECT tbiCustomers.cFirstName 

FROM tb1Customers INNER JOIN tblOrders 

ON tb1Customers.iCustId = 
tbl0rders.iCustId; 


cFirstName 


Harry 
Harry 
Harry 
Harry 
Harry 


SELECT DISTINCTROW 
tb1Customers.cFirstName 

FROM tb1Customers INNER JOIN tblOrders 

ON tb1lCustomers.iCustId = 
tbl0rders.iCustId; 


cFirstName 


Harry 
Harry 


SELECT DISTINCT tb1Customers.cFirstName 

FROM tbiCustomers INNER JOIN tblOrders 

ON tb1Customers.iCustId = 
tblOrders.iCustld; 


nnn 


cFirstName 
ee 


Harry 


All three queries return rows containing “Harry” as the 
only result set field value, but the number of rows returned 
varies. The first query performs a join across tblOrders and 
returns five rows (one for each order). The second query 
returns two rows because with DISTINCTROW Jet returns 
exactly one result row for each row in the table where fields 
are actually being selected from (tblCustomers), and which 
the INNER JOIN clause does not filter out. In the third query, 
the DISTINCT predicate filters out all “visibly” duplicate 
rows, returning only one row in the result set. 

Note that DISTINCTROW only works in queries that list 
more than one table in the FROM clause and where at least 
one of those tables is not represented in the SELECT list. In 
queries that don’t meet these criteria, Jet SQL permits the 
DISTINCTROW predicate but ignores it. Given the obscure 
context in which DISTINCTROW has any effect, I wonder why 
Microsoft chose to place DISTINCTROW in Access queries by 
default. One more comment on these two predicates: in many 
cases DISTINCT and DISTINCTROW return the same result 
data, but DISTINCT always forces the return of a Jet snapshot, 
while DISTINCTROW avoids that limitation. 

The last predicate, TOP, lets you select the records with 
the first n values of the ORDER BY expression. Alternately, 
you can select the records with ORDER BY expression values 
fitting in the first nth percentile. For example, you can select 
the 10 employees with the highest salaries and salaries com- 
posing the top 10 percent of all salaries, respectively. You do 
so by selecting the highest salaries first (using the DESC 
reserved word in the ORDER BY clause) so that the first 10 
records will be the highest salaries: 


SELECT TOP 10 [cLastName], 
{1Salary] 

FROM tblEmployees 

ORDER BY 1Salary DESC; 


[cFirstName], 


SELECT TOP 10 PERCENT [cLastName], 
[cFirstName], [1Salary] 

FROM tblEmployees 

ORDER BY 1Salary DESC; 


You're not yet done with SELECT’s deviant tendencies. You 
need to consider the AS and IN keywords, which are not to be 
confused with the IN operator used in the WHERE clause. AS lets 
you define field names for both calculated and even uncalculated 
columns. Other SQL syntaxes usually do this by preceding the 
expression with an alias name and an “equals” symbol. The 
standard SQL query: 


SELECT cFullName = cLastName + ', ' + 
cFirstName 
FROM tblEmployees; 


becomes: 
SELECT cLastName & ', 


cFullName 
FROM tblEmployees; 


" & cFirstName AS 


in Jet SQL. The IN Keyword lets us include tables in our 
SELECT list that exist in other databases, whether they are 
MDBs, ISAMs (xBASE, Paradox, Btrieve, and others), or ODBC 
databases. With one keyword Jet lets you seize the power of 
its heterogeneous joins features. Don’t miss the subtle sleight 
of hand—you can write heterogeneous join queries dynami- 
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cally that don’t require the external tables to be attached 
tables in the MDB. Also, younever have to do an OpenDatabase 
on the external data. Jet will do one implicitly during the 
CreateDynaset or CreateSnapshot method call. For example, 
you can do heterogeneous joins between tblEmployees and 
both a FoxPro table or an ODBC table: 


SELECT [CustomerID] 

FROM Customer IN "C:\FOXPRO\DATA\SALES" 
"FoxPro 2.0:" 

WHERE CustomerID Like "A*"; 


SELECT [CustomerID] 
FROM Customer IN "" 

“ODBC ;DSN=SQLS ;UID=sa; PWD=" 
WHERE CustomerID Like "A*"; 


Of course, Jet lets you SELECT more than just the fields in the 
tables: youcan use its built-in aggregate mathematical functions 
or your own expressions in the SELECT list. Aggregate functions 
are the mathematical functions, defined by Jet SQL itself, that 
you can use in calculated fields. 


YOU NEVER HAVE TO DO AN OPENDATABASE 


ON THE EXTERNAL DATA. 
se eae 


Jet doesn’t have many aggregate functions, and fortunately 
their names pretty well describe them: SUM, AVG, COUNT, MIN, 
MAX, STDEV, and VAR. Two more, the population functions 
STDEVP (population standard deviation), and VARP (popula- 
tion variance), arenonstandard SQL aggregates provided by Jet. 

In addition to Jet SQL’s functions, you can use any VB3/ 
Access Basic/VBA function in calculated fields. This gives Jet 
SQL lots of horsepower. Additionally, when running your query 
in Access, any functions you create and store in MDB module 
collections become valid functions in calculated fields. How- 
ever, you can’t run queries referencing these user-defined func- 
tions from VB. 

And as soon as you use a nonstandard aggregate, a Basic 
function, user-defined function, or any other Jet-specific SQL 
feature in your query, you make that query unintelligible to an 
ODBC database engine. If you run Jet-specific queries against an 
ODBC database, Jet must send a portion of your query to the 
server, then evaluate the intermediate result set and calculate 
the results of your non-SQL calculated fields locally. 


QUERYING MINDS WANT TO KNOW 
Jet SQL’s JOIN and SELECT commands contain the core of this 
SQL flavor’s idiosyncrasies. But wait, there’s more—espe- 
cially regarding queries and Jet MDB database maintenance. 
Queries can be challenging on secure databases. Perhaps 
you have a table that only certain users can read, but you’d 
like to create a query on that table and let all users access the 
query and see its result set. They can as long as the query 
contains Jet SQL’s WITH OWNERACCESS OPTION keywords. 
You’ve probably used Access to design parameter queries, 
but did you know you can create these objects from Visual 
Basic? Access lets you implicitly create parameters by using 
field names that don’t exist in your database And you can 
specify these parameters’ datatypes by choosing Query/Param- 


eters... from the Access main menu. However, this dialog box is 
just a front end to Jet’s PARAMETERS clause table. The clause 
simply needs to list each parameter and its data type, with 
multiple parameters separated by commas, and end with a 
semicolon. 

To see how this works in practice, take the first query from 
the discussion of predicates: 


SELECT tb1Customers.cFirstName 

FROM tb1Customers INNER JOIN tblOrders 

ON tbiCustomers.iCustId = 
tblOrders.iCustId; 


and tweak it to add a parameter text field—prmcOperator—to 
accompany the other fields in the result set: 


PARAMETERS prmcOperator TEXT; 

SELECT prmcOperator, 
tb1Customers.cFirstName, 
tb1Customers.cLastName 

FROM tb1Customers INNER JOIN tblOrders 

ON tbiCustomers.iCustId = 
tbl0rders.iCustId; 


You can use parameters in a query’s WHERE clause as well as 
its SELECT list (see Table 1). 

You may see crosstab queries as just another Access “user” 
tool, but they are actually useful and easy to implement from VB. 
Crosstab queries result from creating regular GROUP BY que- 
ries and adding TRANSFORM and PIVOT clauses to them. With- 
out crosstabbing, a conventional GROUP BY query produces 
rather vanilla-flavored results: 


SELECT First(tb1Customers.cFirstName) AS 
FirstOfcFirstName, 
First(tblCustomers.cLastName) AS FirstOfcLastName, 
tblOrders.cQuarter, 
Sum(tblOrders.iAmount) AS SumOfiAmount 
FROM tb1lCustomers INNER JOIN tblOrders 
ON tblCustomers.iCustId = tblOrders.iCustId 
GROUP BY tblCustomers.iCustId, tblOrders.cQuarter; 


FirstOfcFirstName FirstOfcLastName cQuarter SumOfiAmount 
I PR NS EN STII 

Harry Smith Q195 50 

Harry Smith Q295 125 

Harry Jones Q194 44 

Harry Jones 0394 55 


You get asummary view of the total purchases made by each 
customer in each quarter stored in the database. That’s fine, but 
you probably want to see the information presented this way 
instead: 


FirstOfcFirstName  FirstOfclastName  Q194 Q195 Q295 Q3 
Harry Smith 50 125 
Harry Jones 44 55 


A superior result set like this takes only a little more effort in 
your Jet SQL query: 
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Sub-Forms: Reuse forms as OCXs within other visual components 
Customization: Tailor components/OCXs for specific applications 
Multi-Project Support: Use and develop components from multiple 
projects within a single application 

Front-End Independence: Use components from any OLE-enabled 
application 


Hi Cross-Environment Compatibility: Components run as Internet 
applications within Web browsers - such as Netscape Navigator 
and Microsoft Explorer - or as parts of Enterprise systems 

| ontainment: Internet and Enterprise components can 
contain multiple OCXs 

H Corporate Data Security: Components use industry-standard 
protocols to securely access enterprise information across internal 
networks, the /ntranet and the Internet 

Java Interoperability: Our VB-compatible tools provide a proven 
and easy-to-learn language with upcoming support for Java 


Run forms and OCXs in Visual Basic and Netscape Navigator. 


Ope Scape Toolkit $145 
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rapidly building World Wide Web components. Use a point-and- 
click environment and Visual Basic compatible script to create 
full-featured applications. These applications can include existing 
OCXs and run directly within Web browsers such as Netscape 
Navigator. 


Ope Extension for OLE Containers 


Our OpenExtensions allow software components to be incorporated } 
within various containers and environments. 1 


The OpenExtension for OLE Containers enables you to embed 
components in OLE containers as OCXs or OLE objects. 
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TRANSFORM Sum(tblOrders.iAmount) AS 
Sum0f i Amount 
SELECT First(tblCustomers.cFirstName) 
AS FirstOfcFirstName, 
First(tblCustomers.cLastName) AS 
FirstOfcLastName 
FROM tb1Customers INNER JOIN tblOrders 
ON 

tb1Customers.iCustId = 


DATABASE DESIGN 


tblOrders.iCustId 
GROUP BY tb1lCustomers.iCustId 
PIVOT tblOrders.cQuarter; 


Notice that I removed the 
Sum(tblOrders.iAmount) AS SumOfi- 
Amount expression from the SELECT list 
and placed it in the TRANSFORM clause 
to make it into the value data used in the 
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Access Combo Box Option Jet SQL DDL data 
type reserved word 

Text TEXT 

Memo LONGTEXT 

Number: Byte BYTE 

Number: Integer SHORT 

Number: Long Integer LONG 

Number: Double DOUBLE 

Number: Single SINGLE 

Date/Time DATETIME 

Currency CURRENCY 

Counter COUNTER 

Yes/No BIT 

OLE Object LONGBINARY 

Value (Variant data—for VALUE 

parameter queries only) 


TABLE 1 Choose Your Weapon. If 

you're writing a SELECT query 
using the PARAMETERS clause or a DDL 
query using the CREATE or ALTER TABLE 
commands, you'll need to specify data 
types using Jet SQL reserved words. Here’s 
alist of those reserved words and how they 
correspond to the more familiar combo 
box choices in the Access Table Design 
and Query Parameter dialogs. 


crosstab. Then I pulled tblOrders.c- 
Quarter from the SELECT list and the 
GROUP BY clause and placed it in the 
PIVOT clause to specify its results to be 
used as the column headers in the 
crosstab. In all other respects the two 
queries match. Comparing them should 
help you get the hang of crosstab queries. 


MAINTENANCE ISSUES 


Now that you can create great Jet SQL 
queries, let’s turn to the unglamorous but 
essential task of maintaining tables, in- 
dexes, and relationships. Here you can 
really leverage your productivity by us- 
ing Jet SQL’s DDL against Jet MDB data- 
bases. For example, you need only one 
SQL query to create a brand new table 
with indexes. To build the table 
tblCustomers, write: 


CREATE TABLE tb1lCustomers 
({cFirstName] TEXT, 
[cLastName] TEXT, 
iCustId INTEGER 

CONSTRAINT ndxCustId PRIMARY KEY); 


You must specify the data type for 
each field listed in the CREATE TABLE 
command. The data types used in the 
DDL queries have a close, but not exact, 
correspondence with the data type name 
listed when you create tables interac- 
tively in Access (see Table 1). 

The CONSTRAINT clause in the 
iCustld specification in the above query 


94 MARCH 1996 Visual Basic Programmer’s Journal 


creates ndxCustld, a primary key index, 
on that field. For PRIMARY KEY you can 
swap in UNIQUE (or nothing at all, fora 
non-unique, nonprimary index) where 
it’s approprviate. 

For multiple-key indexes, you can use a 
standalone CONSTRAINT clause that names 
multiple fields (for details, see the help file 
or printed documentation in VB4, Access 2, 
or Access 7). Both single- and multiple-field 
CONSTRAINT clauses can also use the FOR- 
EIGN KEY subclause. This creates referen- 
tial integrity relationships between tables 
(though you cannot use SQL to set the 
cascade update and delete attributes). You 
can add constraints after creating the table 
by using the ALTER TABLE command in 
place of CREATE TABLE. 


JET ASSUMES THAT 
A FOREIGN KEY 
SHOULD REFERENCE THE 
PRIMARY KEY IN 


THE FOREIGN TABLE. 
Es 


To demonstrate some of these con- 
cepts, consider a typical ALTER TABLE 
query in DDL. It uses ALTER TABLE with 
a FOREIGN KEY specification to assure 
referential integrity between tblOrders 
and tblCustomers: 


ALTER TABLE tblOrders 

ADD CONSTRAINT ndxCustId FOREIGN KEY 
(iCustId) 

REFERENCES tb1lCustomers (iCustId); 


I used an explicit specification of the 
tblCustomers.iCustld field at the end of 
the above query, though I could have 
skipped it. Jet assumes that a foreign key 
should reference the primary key in the 
foreign table. You can build nonprimary 
key references when the field is specifi- 
cally listed. 

You can also use ALTER TABLE with 
the ADD COLUMN, DROP COLUMN, and 
DROP CONSTRAINT reserved words to 
add and delete fields or indexes. You can 
also create indexes with CREATE INDEX 
and delete them with DROP INDEX. You 
can delete a whole table and all of its 
indexes with DROP TABLE. 

Unlike the CREATE TABLE and ALTER 
(Saeiaa commands, CREATE INDEX lets 
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you create indexes with descending ex- 
pressions as well as with IGNORE NULL 
and DISALLOW NULL validation rules 
(again, see the help file or printed docu- 
mentation in VB4, Access 2, or Access 7 
for details). 

This concludes our crash course in Jet 
SQL. If you followed this discussion, you 
have almost completely mastered what 


you need to know about Jet’s JOIN clause, 
predicates, aggregates, AS andIN clauses, 
the WITH OWNER ACCESSOPTION fea- 
ture, parameter and crosstab queries, and 
DDL commands. Now you have at your 
disposal a powerful facility for making 
your applications adept at data manipula- 
tion and definition, and folks will be com- 
ing to you for help with their queries. Xl 
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Create Windows 


API Object Controls 


Using a Timer control is one thing, 
but knowing how it works 
internally is another. 


by Richard Hale Shaw 


yj his month, I'll take a break from the DigitalClock 
control and look at a different issue: creating objects 
a that encapsulate the Windows API. 

As any reader of this column knows, objects are the wave 
of the future. While OLE has been a portent of an object- 
oriented Windows, OLE is only the beginning. In future ver- 
sions of Windows, most of your programming will involve 
using objects. Rather than using APIs, you'll instantiate an 
object for a particular Windows service, and interact with 
that object in order to put the service into use. 

This kind of object-oriented Windows used to be termed 
“Cairo,” but the concept of Cairo has changed a great deal in the 
last several months. A lot of what we once thought of as Cairo 
will appear in Windows NT 4.0 this spring: the Win95 shell, PC 
card support, and distributed OLE. Instead, Cairo will now 
include connectivity and Internet-related features that will be 
more powerful than what was originally envisioned. 

But a significant aspect of all new versions of Windows is 
that most new Windows services—and eventually, many older 
ones—will be packaged as OLE controls. And many of these 
controls will provide encapsulations of various APIs. For 
example, there are plenty of APIs whose use requires a 
sequence of events such as these: 


e Initialize a data structure. 

¢ Call an API to register the data structure with Windows. 

¢ Call another API to establish a callback function address. 
¢ Call various APIs to actually perform the required service. 
¢ Implicitly register an application window with Windows by 
passing a window handle as an argument to various API 
functions. 

* Respond to invocations of the callback function by Windows. 
¢ Respond to messages sent to your application window as a 
result of calling various APIs. 

¢ Call an API to de-register the data structure and terminate 
the service. 


This kind of thing goes on all the time in Windows, anda 
great deal of what an object-oriented development tool such 


Richard Hale Shaw is a contributing editor to Visual Basic 
Programmer’s Journal and PC Magazine. He’s currently complet- 
ing Visual Programming++, a book about Visual C++. He lives in 
Ann Arbor, Michigan, and can be reached on CompuServe at 
ae 155, or the Internet at 3998368@mcimail.com. 


as the Microsoft Foundation Classes provides is encapsula- 
tion of the core behavior that makes all this work. But some- 
times MFC by itself isn’t enough. Using an MFC object means 
instantiating it and writing code to utilize its member func- 
tions and data members. You can access an OLE control, 
however, simply by dragging and dropping it from a tool 
palette into your program. And many OLE controls let you 
access data through properties (exposed in property sheets) 
and activate functionality by setting other properties (such 
as an Enabled property). So you often don’t have to write any 
code to use an OLE control. 


INTRODUCING THE TIMER APIs 

A great example of a set of APIs that you can easily encapsu- 
late—not just with an MFC object, but through an OLE control— 
are the Windows Timer APIs. The Timer APIs let you implement 
periodic processing that’s initiated on receipt of a WM_TIMER 
message. They let you create a Windows timer that will send 
WM_TIMER messages to a given window in your application. 
The timer sends the WM_TIMER messages on a regular basis at 
an interval that you specify when you create the timer. You have 
to add WM_TIMER handling to the specified window, or design 
your program’s message loop to monitor the receipt of these 
messages and then have the window procedure dispatch them 
to a particular window. 

Using the Timer APIs requires you to make a few decisions. 
First, of course, you have to decide what your program is going 
to do every time it gets a timer message. You create a handler for 
WM_TIMER messages (a message-mapped override of 
CWnd::OnTimer in an MFC application); or, instead, specify a 
callback function that Windows will directly invoke. You’ll also 
have to decide how long the timer interval—the interval be- 
tween WM_TIMER messages—will be. You specify this interval 
in milliseconds: the faster the timer, the smaller the timer 
interval. Thus, a fast timer might generate WM_TIMER messages 
10 times a second (a 100-millisecond interval), amore moderate 
timer might generate messages every second (a 1000-millisec- 
ond interval), and a slower timer would generate a WM_TIMER 
message every 10 seconds (a 10,000-millisecond interval). 

To create a timer, call the SetTimer API function 
(CWnd::SetTimer in MFC), and specify the interval, the ad- 
dress of the timer callback function (or NULL to handle the 
WML_TIMER messages yourself), and a timer ID. The timer ID 
lets you create more than one timer, where each WM_TIMER 
message includes the ID of the timer that generated the 
message. (This ID is passed as a parameter to CWnd::OnTimer 
in an MFC application.) Once you call SetTimer, the WM_TIMER 
messages will continue at the appropriate interval until you 
call the KillTimer API (CWnd::KillTimer in MFC), passing it 
the timer ID as an argument. KillTimer will destroy the timer. 

One problem with the Windows Timer APIs is that there’s 
no convenient way to stop and restart the same timer, or to 
change the timer interval on a timer. If you want to temporarily 
stop and then restart a timer, you have to call KillTimer to 
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destroy the timer, and then SetTimer to re-create it. And you 
have to use the same approach to change the timer interval. 
There’s no way to change the interval in mid-stream, so you'll 
have to go through the creation-destruction process again. 

This can end up being a lot of work. MFC helps, of course, 
but its encapsulation of the Timer APIs is kind of thin. And it 
doesn’t solve the stop-restart and interval change problems. 
So having a timer control—an encapsulation of the Timer 
APIs in the form of an OLE control—will definitely help. 

Fortunately, Visual Basic 4.0 comes with such a control. 
You probably saw it in the form of a VBX in previous versions 
of VB. The VB4 Timer control can be drag-and-dropped into 
a form or dialog. You can specify the timer interval through 
the Interval property, and just set the Enabled property to 
True to enable the control. Whenever the Enabled property is 
True and the Interval property is greater than zero, the Timer 
control will send Timer Events to its parent form or dialog at 
the specified interval. Probably the only disadvantage to 
using the Timer control is that it’s available only in the Visual 
Basic 4.0 environment. You can’t use it in VC4 or other OLE 
control containers. 

Just using the Timer control is one thing, but knowing how 
it works internally is another. So I decided to clone the Timer 
control and figure out how it works. In this column, I'll show 
you how I built my own Timer control—one that you can use 
in VC4 as well as VB4. 


ENCAPSULATING THE TIMER APIs 

I started by using ControlWizard to generate a pretty vanilla 
control. The one option that I took advantage of was “Invis- 
ible At Runtime,” which causes ControlWizard to add the 
OLEMISC_INVISIBLEATRUNTIME bit to the miscellaneous reg- 
istry settings in the generated code: 


static const DWORD BASED_CODE 
_dwTimerOleMisc = 
OLEMISC_INVISIBLEATRUNTIME 
OLEMISC_ACTIVATEWHENVISIBLE | 
OLEMISC_SETCLIENTSITEFIRST | 
OLEMISC_INSIDEOUT | 
OLEMISC_CANTLINKINSIDE | 
OLEMISC_RECOMPOSEONRESIZE; 


IMPLEMENT_OLECTLTYPE(CTimerCtrl, 
IDS_TIMER, _dwTimerOleMisc) 


With this bit-setting option on, the control container knows 
to display the control only during development, but not at 
run time. After all, timers need to be used programmatically, 
but the end user doesn’t need to see them displayed in a form 
or a dialog. Therefore, the VB4 and VC4 environments will 
display the control in a form or dialog, but at run time, VB4 
and an MFC4 application won’t display the control. | made the 
Timer Control part of an OCX called “SHAW WINAPI 
OBJECTS.OCX,” and the associated programmatic ID 
SHAWWINAPIOBJECTS.TimerCtrl.1, the name that refers to 
this control in the system registry. With these steps in place, 
I could now start modifying the code generated by 
ControlWizard. 

Getting the initial timer support in place wasn’t too diffi- 
cult. The VB4 timer control uses two properties: Enabled, a 
BOOL stock property, and Interval, a short-integer custom 
property. | used ClassWizard to add support for these. For the 
Interval property, I selected the ClassWizard option for creating 
a pair of Get/Set methods to create a pair of member functions, 


GetInterval and SetInterval, for controlling access to the Interval 
property. I additionally needed to create a data member to store 
both properties, so I used the Visual C++ 4.0 ClassView to add 
the new data member. You simply select the ClassView tab to 
display the ClassView, right-click on the class name, select “Add 
Function” (see Figure 1), and enter the new data member type 
and name (see Figure 2). With these two properties in place, | 
had to add some program logic: 


e Code to start the timer when the control’s window was 
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FIGURE 2 Adding New Data Members to the Class. After selecting 
“Add Variable...” in Class View, you can specify the data 
type and name of a new data member and add it to the class. 
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created, provided that Enabled was True 
and Interval was greater than zero. 

¢ Code to detect changes to either of 
these properties, and start or stop the 
timer depending on their settings. 

¢ Code to save changes to the Interval 
property whenever it changed. 

¢ Code to stop the timer, provided it was 
already running, when the control’s win- 
dow was destroyed. 


Code that starts a timer would use 
CWnd::SetTimer; code that stops the 
timer would use CWnd::KillTimer. To 
accommodate these changes, I addeda 
data member, m_isRunning, which 
would always identify the state of the 
timer control and whether the timer 
was running. This became particularly 
useful when the Enabled property 
changed, because the default implemen- 
tation of this stock property is through 
a data member and a member function 
in COleControl: COleControl::m_ 
bEnabled and COleControl::OnEnabled- 
Changed. This default implementation 
doesn’t give you any granular control 
over the actual change to the Enabled 
property, so you have to distinguish 
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between the previous state of the con- 
trol (as defined by m_isRunning) and 
the current state of the control (as re- 
turned by COleControl::m_bEnabled and 
my own m_interval). Fortunately this 
just required a little housekeeping in 
my OnEnabledChanged override: 


void CTimerCtr1: 
{ 


:OnEnabledChanged( ) 


COleControl: :OnEnabledChanged(); 
if(m_bEnabled && (m_interval > 0)) 
{ 
if(m_isRunning) 
return; 
SetTimer(1,m_interval,NULL); 
m_isRunning = TRUE; 
} 
else 
{ 
if(!m_isRunning) 
return; 
KillTimer(1); 
m_isRunning = FALSE; 
} 


I had to add similar logic to the 
SetInterval function. 
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CREATING A CUSTOM EVENT 

With the timer running, the control’s 
window would get WM_TIMER messages 
at the appropriate interval (remember 
that because COleControl is a CWnd- 
derivative, every COleControl has a win- 
dow—an HWND—associated with it). I 
needed to fire an event to the control 
container’s window, which is the form 
or dialog that contains the control. So I 
used ClassWizard to add support for a 
custom Timer event, using its Add Event 
pane. ClassWizard will make a few 
changes to your control source code 
when you add this custom event. First, 
it adds an entry to the event map (a lot 
like an MFC message-map) to define a 
new custom event and specify the event- 
firing function: 


BEGIN_EVENT_MAP(CTimerCtr1, 
COleControl) 
//{{AFX_EVENT_MAP(CTimerCtr1 ) 
EVENT_CUSTOM”Time”, FireTimer, 

VTS_NONE) 
//}}AFX_EVENT_MAP 
END_EVENT_MAP( ) 


It also defines the event-firing function 
as an inline function in your control class 
definition: 


//{{AFX_EVENT(CTimerCtr1) 
void FireTimer() 


{FireEvent(eventidTimer, EVENT_PARAM( 
VTS_NONE));} 
//}}AFX_EVENT 


The variable, eventidTimer, is simply 
an ID that ClassWizard assigns to a cus- 
tom event in a set of enumerated values: 


enum { 
//{{AFX_DISP_ID(CTimerCtr1) 
dispidInterval = 1L, 
eventidTimer = 1L, 
//}}AFX_DISP_ID 


Note that ClassWizard uses this same 
set of enums to assign an ID to the Interval 
property as well. 

With the custom event support in 
place, the control can now fire Timer 
events to the control container by calling 
the FireEvent function. Sol added an over- 
ride of CWnd::OnTimer—which will be 
called whenever the control gets a 
WML_TIMER message from the timer—and 
had the override call FireEvent: 


void CTimerCtr1: 
nIDEvent ) 

{ 
if (m_isRunning) 


:OnTimer(UINT 
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inc. 


FireTimer(); 
COleControl::OnTimer(nIDEvent); 


Note that the implementation here lets 
the control fire a timer event whenever it 
gets a WM_TIMER message, and as long 
as m_isRunningis True. This would let me 
alter the design of OnEnabledChanged in 
a future implementation of the control so 
that the timer would keep running even if 
Enabled was False, but the timer mes- 
sages would be translated into events 
only if Enabled was True. 


CREATING A NONRESIZABLE WINDOW 

With this, the basic timer control infra- 
structure was in place. But now I had 
two additional problems. The first was 
to draw a nonresizable bitmap on the 
control window during development 
(remember, at run time the control won’t 
be seen because of the OLEMISC_ 
INVISIBLE-ATRUNTIME bit). Drawing the 
bitmap wasn’t too difficult, and that was 
added as the implementation of the 
control’s OnDraw function. OnDraw, as 
you may recall, is a virtual function in 
COleControl that will be invoked when- 


Desaware 


Software components for Windows 


A database is not the only 
way to store things. 


Somtimes you have information to store that does 
not lend itself to a database structure. Or perhaps 


you want to create a private file format. Or to save 
data without the overhead of a database. 


StorageTools’ 


wlets you easily tap into a] powerful new feature of 
Windows called OLE § Bs J 
from within Visual Basic or VBA. Cae custom 
file formats where each file can contain a complete 
hierarchical file system—multiple streams of data in 
their own directory structure. Allows you to add 
features such as transactioning and incremental 
saves to your applications. Now you can take 
advantage of the same file capabi lities used by 
Microsoft in its own Office applications. 


Easily work with the registration database 


INNEW PRODUCT: BXtaeeecertl navigate the registration database with familiar Basic 
commands. Includes 16 and 32 bit OLE controls for Windows-95, NT 3.51 and 
Windows 3.1x. Supports VB 4.0 and other OLE Control containers. Only $129. 
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ever the control needs to redisplay it- 
self. By overriding this virtual function 
ina COleControl-derivative, youcanadd 
your own drawing code to the control. 
The first parameter to OnDraw is the 
device context to draw on. The second 
and third parameters specify the bound- 
aries of the control’s rectangle and the 
portion of that rectangle to be re-drawn, 
respectively. 

Iscreen-snapped the bitmap used by 
the VB4 timer control to create a new 
bitmap, pasted it into the VC4 bitmap 
editor, and then added it to the control's 
resources. The OnDraw override in the 
Timer control begins by loading that 
bitmap from the resources: 


CBitmap bitmap; 
bitmap. LoadBitmap(IDB_BITMAP1); 


CBitmap is the MFC bitmap class, de- 
rived from CGdiObject, which encapsu- 
lates most of the Windows GDI APIs. 
OnDraw instantiates a CBitmap object, 
and LoadBitmap loads the bitmap and 
attaches it to that object. 

Next, OnDraw instantiates a CPicture- 
Holder object to display the bitmap in the 


structur 
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control’s window. CPictureHolder was 
designed for implementing picture prop- 
erties (an OLE control feature that origi- 
nated in VBXs), and for displaying 
bitmaps, icons, and metafile picture prop- 
erties in a window. You can use 
CPictureHolder::CreateFromBitmap to 
associate a CBitmap with a CPicture- 
Holder: 


CPictureHolder picHolder; 
picHolder.CreateFromBitmap(bitmap, 
NULL, 
FALSE); 


Then, tell the CPictureHolder object 
to draw the bitmap in a specified device 
context with CPictureHolder::Render: 


picHolder.Render(pdc, 
rcBounds); 


rcBounds, 


CBITMAP IS THE MFC 
BITMAP CLASS, DERIVED 
FROM CGDIOBJECT, WHICH 
ENCAPSULATES MOST OF 


THE WINDOWS GDI APIs. 
eae as | 


This takes care of getting the bitmap 
to display properly when the control is 
drag-and-dropped on a form. Note, by 
the way, that OnDraw doesn’t have to 
release the original bitmap through a 
call to CGdiObject::DeleteObject: the 
CGdiObject destructor does this for you 
automatically. 

The second and more difficult prob- 
lem involved getting the control to dis- 
play in a nonresizable window. As with 
the original VB4 timer control, I didn’t 
want a developer to be able to resize the 
control window. Instead, the control 
should snap back to its original size 
whenever you try to resize it. After a 
great deal of hunting (and a few flurries 
of e-mail to a friend on the MFC team at 
Microsoft), I found two helpful func- 
tions in COle-Control: OnSetExtent and 
OnSetObjectRects. 

COleControl::OnSetExtent encapsu- 
lates the implementation of the control’s 
IOleObject::SetExtent function, to 
handle resizing the control. By overrid- 
ing this function, I was able to force the 
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control always to be resized to the same 
size: 


BOOL CTimerCtr1: 
IpSizeL ) 


:OnSetExtent( LPSIZEL 


IpSizeL->cx = IpSizeL->cy = 
MinMaxSize; 
return TRUE; 


Returning True indicates that the size 
change was accepted (when, of course, 
the function has forced a specific size). 
The MinMaxSize value contains the 
control’s bitmap dimensions. 

The other function, COleControl::On- 
SetObjectRects, implements [OlelIn- 
Place-Object::SetObjectRects to handle 
repositioning and resizing of the 
control’s window. I didn’t need an over- 
ride of this function in place to get the 
control to display properly in VB4 or 
VC4—but it made a difference in how 
the control was displayed by the con- 
trol Test Container, which comes with 
VC4. Test Container appears to do some 
of its drawing differently from other 
containers. I wasn’t worried about this, 


Now try to ship it... 
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because control users have no reason 
to use Test Container. But, to make the 
control look a little better there, I over- 
rode this function and plugged in the 
appropriate control dimensions: 


BOOL CTimerCtr1::OnSetObjectRects( 
LPCRECT 1pRectPos, 
LPCRECT lpRectClip ) 
CRect* 1pPos = (CRect*)1pRectPos; 
CRect* IpClip = (CRect*)1pRectClip; 
1pPos->right = IpClip->right = 
(1pPos->left + MinMaxSize); 
1pPos->bottom = 1pClip->bottom = 
lpPos->top + MinMaxSize; 
return 
COleControl: 
ip); 


:OnSetObjectRects(1pPos,1pCl 


Finally, I had one particular problem 
concerning VB4 itself. I noticed that the 
timer simply didn’t work correctly in VB4, 
even though it worked just fine in the 
control Test Container as well as in an 
MFC4 application. In VB4, the timer wasn’t 
being created when Enabled was True 
and Interval was greater than zero. 


Software components can help you build great 


programs in record time, but if your end user has 
the wrong version of an OCX, VBX, or DLL on 


their system, your great program can crash like a 


house of cards. 
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A little debugging showed that the 
control’s OnCreate override wasn’t being 
called when the control was used in VB4, 
and thus that the control’s window was 
never being created. I had to conclude 
that, by default, VB4 doesn’t get the con- 
trol to create a control window if the 
control is “Invisible At Runtime” like this 
control was. (Apparently, there’s no stan- 
dard on what a container should do with 
such a control, hence the differences in 
behavior between VB4 on the one hand, 
and VC4 and the Test Container on the 
other hand.) The only way to ensure that 
the control’s window was created was to 
override COleControl::OnSetClientSite, 
which is called whenever the container 
initializes an OLE object’s client site: the 
point at which the object connects to and 
communicates with the container. 


A GREAT EXAMPLE 
OF A SET OF APIs THAT 
YOU CAN EASILY 
ENCAPSULATE ARE THE 


WINDOWS TIMER APIs. 
Baas eT 


Because this has to be done by every 
container for every control, an override 
of OnSetClientSite could call COle- 
Control::RecreateControlWindow, 
which forces a control to destroy its 
window (if it has one), and then re- 
create that window or initially create it, 
if it didn’t have one. Even though the 
control worked fine in Test Container 
and MFC4 applications without this 
code, it allowed my control to work in 
VB4 also: 


void CTimerCtr1: 
{ 


:OnSetClientSite() 


RecreateControlWindow(); 
} 


I’ve provided a VB4 program that shows 
the use of both my timer control clone and 
the original timer control in VB4 (see Figure 
3). You can download this program from 
the Magazine Library of the VBP/Forum on 
CompuServe (type “GO WINDX” with 
WinCIM and search for VP0396.ZIP), the 
VBPJ Development Exchange World Wide 
Website (http://www.windx.com), the VBPJ 
siteon The Microsoft Network (GO WINDX), 


or the VBCD. Xl 
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NT Events are a Terrible 


Thing to Waste 


Read event logs on Windows NT 
with 32-bit VB 4.0 code and 
32-bit API calls. 


by LJ. Johnson 


| fyouaren’t running a Windows NT server or workstation, 
don’t read any further. If you are not an administrator for 

‘ an NT server and/or workstation, or if you never have 
hardware or software problems on NT, this article isn’t for you. 
But if any of this applies to you, you probably already know 
something about the event logs. Through a defined API, you can 
use the event logs as a single place to store and retrieve informa- 
tion about security events, system events, or application events. 
In this column I'll demonstrate how to read the event logs 
programmatically from the 32-bit version of Visual Basic 4.0. 

Windows NT creates and maintains a set of event logs: 
System, Security, and Application. Physically, the three logs are 
stored as three files in the \%SystemRoot%\system32\config 
directory as: SysEvent.Evt, SecEvent.Evt, and AppEvent.Evt 
(where %SystemRoot% is the Windows NT directory). Examine 
the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControl- 
Set\Services\Eventlog key in the 32-bit registry for further 
information on these logs. If you haven’t yet used the Event 
Viewer applet in NT, bring it up now and browse the three event 
logs before you read the rest of column—doing so will make it 
easier to understand the concepts. 

You can look at the event logs on your local machine, or on 
any other NT computer on the network to which you have read 
rights to that event log. It is not a trace facility, and it does 
consume resources such as disk space and logging time, but it 
can be invaluable for tracking subtle problems. For example, 
consider an application that logs all low-memory conditions. 
Several low-memory occurrences in the log might indicate that 
the system needs more memory in order to successfully run this 
application, or that the application has a bug that causes a 
memory leak over time. 

The System log records events logged by the NT system 
components. You do not have to enable system logging—it 
occurs automatically. On my system, the System log contains 
these records: 


e Application Popup: System Popup—Wrong Volume. The wrong 
volume is in the drive (This refers to my CD-ROM drive. I had 
changed a CD too early). 


LJ. Johnson is a technical consultant on the Mary Kay InTouch 
project at Mary Kay Cosmetics in Dallas, Texas. He has been 
programming in Visual Basic since 1.0, and is a section leader on 
the VBPJ Forum on CompuServe. Reach him on CompuServe at 
74777, 3047. 


e The browser has forced an election on network 
\Device\Nbf_EInk32 because a master browser was stopped. 
e The Event Log service was started. 

e Debug: ShareThisPrinter NetShareDel failed, Printer 
LP_LaserJet3 sharename LJet3, Error 2114, deleting share. 

¢ The redirector has timed out arequest to ntbr61. ([got this RAS 
message when ] lost the connection to the remote server). 

e User configuration data for parameter COMI overriding firm- 
ware configuration data. 


The Security log records security events. You must enable 
security logging in the User Manager, under the Audit menu item 
of the Policies menu, for success or failure of such things as: 


e Logon and logoff. 

e File and object access. 

e Use of user rights. 

e User and group management. 

e Security policy changes. 

e Restart, shutdown, and system. 
e Process tracking. 


Using these settings in conjunction with the settings in File 
Manager under the Auditing menu item of the Security menu, 
you can actually look at who reads, writes, executes, deletes, or 
changes permissions on a single file or group of files. 

The Application log is perhaps the most interesting of all the 
logs. The Security log is designed primarily for system adminis- 
trators, although logging which users accessed or executed a 
particular file might be useful for some applications. The System 
log is a mixed bag. 

The Application log, however, is utilized by applications— 
those things we build for a living. For example, you might build 
a program to automatically check an entire group of NT servers 
and workstations daily for certain types of events in the Appli- 
cations log (or, for that matter, the System or Security log), and 
warn the network supervisor if any were found. Or you might 
want to save certain types of event log entries to a text file before 
clearing (deleting) that log. I won’t cover writing to the Applica- 
tion log in this column, but it is possible to do it from VB. That 
topic might make a good future column. 

Reading an event log is more complicated than you might 
first expect. It requires a number of 32-bit API calls, and a 
number of workarounds to some of the limitations of VB. Be- 
cause of the complexity, the entire functionality is encapsulated 
in an in-process OLE server. 

I should say something here about error handling: the VB 4.0 
manuals give two ways to pass error information from the OLE 
server back to the calling application—using the Err object and 
raising an error in the calling app, or passing the error informa- 
tion back from each exposed method or property. Because I did 
not like either of these options, I used a third. The two main 
public methods, OpenAnyEventLog and ReadEventEntries, re- 
turn False if any errors occur while you're opening or reading 
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Public Function ReadEventEntries() As Long 


Dim pbyteBuffer() As Byte 
‘missing declarations 


‘missing code to check EventType has been 
' set _and set the starting date and time bias 


' Make sure that the event log has been opened 
If mingEventLogHwd = &HFFFFFFFF Then 
" Has never been set -- see Initialize event 
LastEventErrorNumber = (ERR_LOG_NOT_OPENED + _ 
vbObjectError) 
LastEventErrorSource = EVENT_SOURCENAME & _ 
"ReadEventEntries” 


“has not been opened yet. Use” & _ 
OpenAnyEventLog property.” 
ReadEventEntries = False 
mlngCount = 0 
Exit Function 
ElseIf mlngEventLogHwd <> 0 Then 
plngEventLogHwd = mlngEventLogHwd 
Else 
' Error info set when set the Server Name 
ReadEventEntries = False 
mlngCount = 0 
Exit Function 
End If 


" See how many event records are in this log 


True Then 
pingNumRecords = CountEventRecords 
End If 


If pingNumRecords <= 0 Then 
" No records -- set number of records to zero 
"and exit the function 
ReadEventEntries = False 
mingCount = 0 
Exit Function 
Else 
" Redimension the type array to 
" total number of records 
ReDim colEventRecord(1 To pingNumRecords) _ 
As EventRecord 
End If 


If mingEventReadLogForward = True Then 
plngReadFlags = EVENTLOG_SEQUENTIAL_READ Or _ 
EVENTLOG_FORWARDS_READ 
Else 
plngReadFlags = EVENTLOG_SEQUENTIAL_READ Or _ 
EVENTLOG_BACKWARDS_READ 
End If 


‘missing code to initialize variables 


" Loop thru the record numbers 
Do While plngNumUnfilteredRecords < plngNumRecords 


plngNumUnfilteredRecords ) 

If plngNumBytesToRead > 16384 Then 
pingNumBytesToRead = 16384 

ElseIf plngNumBytesToRead < 4096 Then 
plngNumBytesToRead = 4096 

End If 


TryAgain: 
ReDim pbyteBuffer (0 To plngNumBytesToRead - 1) 


LastEventErrorDescription = "The Event Log” & _ 


If API_NumberOfEventLogRecords(pIngEventLogHwd) = _ 


plngNumBytesToRead = 1024 * (pIngNumRecords - _ 


properties and an index value in the calling program. 


" Read the event log (multiple records) and 

" check for errors 

plngRtn = ReadEventLog(pIngEventLogHwd, _ 
plngReadFlags, plngReadRecordOffset, _ 
pbyteBuffer(0), plngNumBytesToRead, _ 
plngNumBytesRead, plngMinNumBytesNeeded) 


If plngRtn = False Then 
If Err.LastD11Error = ERROR_HANDLE_EOF Then 
" End of the records 
Exit Do 
Elself Err.LastDl1lError = _ 
ERROR_INSUFFICIENT_BUFFER Then 
' OK, 16K wasn't big enough -- set to 
" the value returned by the function 
' for the number of bytes needed 
plngNumBytesToRead = plngMinNumBytesNeeded 
GoTo TryAgain 
Else 
‘missing code to set the substitute error 
‘properties as above 
ReadEventEntries = False 
mlngCount = 0 
Exit Function 
End If 
End If 


ReDim Preserve pbyteBuffer(0 To _ 
plngNumBytesRead - 1) 

pstrMultiRecBuffer = Space$(pIngNumBytesRead) 

CopyMem ByVal pstrMultiRecBuffer, _ 
pbyteBuffer(0), plngNumBytesRead 

Erase pbyteBuffer 


" Loop for each record in the buffer 
Do While Len(pstrMultiRecBuffer) > 0 


If plngNumUnfilteredRecords > _ 
plngNumRecords Then 
Exit Do 

End If 


plngNumUnfilteredRecords = _ 
plngNumUnfilteredRecords + 1 


" Get the length of the next record and 
" set the buffer to that length 
plngRecLen = CVL(Mid$(pstrMultiRecBuffer, 1, 4)) 
pstrBuffer = Mid$(pstrMultiRecBuffer, _ 
1, plngRecLen) 
pstrMultiRecBuffer = Mid$(pstrMultiRecBuffer, _ 
plngRecLen + 1) 


" Get the raw info from the event log 

pingRecNum = CVL(Mid$(pstrBuffer, 9, 4)) 

pvntAddDate = CVL(Mid$(pstrBuffer, 13, 4)) 

pvntTimeGenerated = DateAdd("s", _ 
CLng(pvntAddDate) - plngBiasTimeSecs, _ 
pyntStartDate) 

plngEventID = CVL(Mid$(pstrBuffer, 21, 2)) 

plngEventIdForFile = CVL(Mid$(pstrBuffer, _ 
21, 4)) 

pintEventType = CVI(Mid$(pstrBuffer, 25, 2)) 

‘missing code to extract rest of items 

‘from the buffer 


' Get the EventSourceName and 

' EventComputerName strings 
pstrTmp = Mid$(pstrBuffer, 57) 

On Error Resume Next 

plngPos = InStr(pstrTmp, Chr$(0)) 


CONTINUED ON PAGE 106. | 


LISTING 1 Read All About It. The ReadEventEntries method is the main interface method for the server. It reads all the entries in the 
log you selected through the OpenAnyEventLog property, and filters the records if requested. It also fills in a private type array 
for each log item in the filtered or unfiltered list. Access the various pieces of each log item, such as EventID and Event Type, through 
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LastEventErrorDescription public properties. 


CONTINUED FROM PAGE 105. 


If plIngPos > 0 Then 
pstrEventSourceName = Mid$(pstrTmp, 1, _ 
plngPos - 1) 
End If 


If plngPos > 0 Then 
pstrTmp = Mid$(pstrTmp, plngPos + 1) 
plngPos = InStr(pstrTmp, Chr$(0)) 
If plngPos > 0 Then 
pstrEventComputerName = Mid$(pstrTmp, _ 
1, plngPos - 1) 
End If 
End If 


" Get the message string 
If pintNumStrings > 0 Then 
pstrStrings = Mid$(pstrBuffer, _ 
plngStringOffset +1, _ 
(pIngDataOffset - plngStringOffset)) 
End If 
pstrMsgString = _ 
ResourceString(pstrEventSourceName, _ 
pintNumStrings, pstrStrings, 
plngEventIdForFile) 


Select Case CLng(pintEventType) 
Case EVENTLOG_SUCCESS 
pstrEventType = "Success" 
‘missing code to set string for other 
‘types of EventType return value 
End Select 


" For no filter, all records match 
If mingFilterType = Filter_Type_None Then 
plngIsMatch = True 


" Have a filter -- this record may or 
"may not match 
Else 
PplngIsMatch = False 
Select Case milngFilterType 
Case Filter_Type_TimeBefore 
If CDate(pvntEventTimeWritten) < _ 
CDate(mvntFilter) Then 
plngNumFilteredRecords = _ 
plngNumFilteredRecords + 1 
plngIsMatch = True 
End If 
Case Filter_Type_EventID 
If CLng(plngEventID) = _ 
CLng(mvntFilter) Then 
plngNumFilteredRecords = _ 
plngNumFilteredRecords + 1 
plngIsMatch = True 
End If 
‘missing code to handle other 
‘types of filters 
End Select 
End If 


" Only add to array if this is a matching 
“ record (with no filter, all records match) 
If plngIsMatch = True Then 
If mingFilterType = Filter_Type_None Then 
plngRecCount = plngNumUnfilteredRecords 
Else 
plngRecCount = pingNumFilteredRecords 
End If 


colEventRecord(pIngRecCount) ._ 
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The OpenAnyEventLog method takes a single parameter, 
ServerName, and returns either True or False. Before calling this 
method, you must set the TypeEventLog. If you do not set the 


EERE TE a RR ER NT RET TT 


the event logs. The same information that could be returned 
through the Err properties is instead returned through the 
LastEventErrorNumber, the LastEventErrorSource, and the 


EventRecordNum = plngRecNum 
colEventRecord(pIngRecCount) ._ 


Ea aS ne | 


EventTimeWritten = pvntEventTimeWritten 
‘missing code to fill rest of type array 


If plngSidLength = 0 Then 
colEventRecord(pIngRecCount) ._ 
EventUserName = "N/A" 
Else 
pstrimp = Mid$(pstrBuffer, _ 
plngSidOffset, plngSidLength) 
pstrSidi=:|"" 
For pintInnerLoop = 1 To pIngSidLength 
pstrSid = pstrSid & _ 
Format$(Hex$(Asc(Mid$(pstrTmp, _ 
pintInnerLoop, 1))), "00") &"" 
Next pintInnerLoop 
colEventRecord(pIngRecCount) ._ 
EventUserName = pstrSid 
End If 


If plngDataLength > 0 Then 

pstrimp = Mid$(pstrBuffer, _ 
plngDataOffset + 1, _ 
plngDataLength) 

pstrData = "" 

" Convert to hex only if less than 256 

" bytes or if the user wants it that way 

If mlngEventDataReturnHex = False Then 
If Len(pstrTmp) > 256 Then 

pstrData = pstrTmp 


Else 
For pintInnerLoop = 1 To _ 
plngDataLength 
pstrData = pstrData & _ 
Format$(Hex$(Asc_ 
(Mid$(pstrTmp, _ 
pintInnerLoop, _ 
12) ree 40 Oi avian 
Next. pintInnerLoop 
End If 
Else 
For pintInnerLoop = 1 To _ 
plngDataLength 


pstrData = pstrData & _ 
Format$(Hex$(Asc(Mid$_ 
(pstrTmp, pintInnerLoop, _ 
Le)S) Dicey OO is Grates 
Next pintInnerLoop 
End If 
colEventRecord(pIngRecCount) ._ 
EventData = pstrData 
Else 
colEventRecord(pIngRecCount) ._ 
EventData = "N/A" 
End If 
End If 
Loop 
Loop 


" Re-adjust the number of items in array if it 
“was filtered, and set the number of records 
in the module-level variable 
If mlngFilterType <> Filter_Type_None Then 
ReDim Preserve colEventRecord(1 To _ 
plngNumFilteredRecords) 
mlngCount = plngNumFilteredRecords 
End If 


‘ 


On Error GoTo 0 
End Function 
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Let VBA Companion simplify OLE Automation and Visual Basic 
for Applications programming by allowing you to browse, search, 
and print all of the OLE objects installed on your system. VBA 
Companion provides a complete, full-featured OLE object reference 
(properties, methods, events, constants, help file topics, and code 
templates). Unlike built-in object browsers, it supports system-wide 
searches, user annotations, and even produces presentation-quality 
documentation for objects that you use or develop. Whether you 
use Excel, Access, Word, Visual Basic, Project, OCX controls, or 
any other OLE-aware application, you'll agree that VBA 

OLE Objects VBA Companion _OLE Objects with VBA Companion Companion is top dog among object browsers. 


Dze\ APEX Software Corporation * 4516 Henry Street Pittsburgh, PA 15213 « Phone (412) 681-4343 © Fax (412) 681-4384 * Web: hittp://www.apexsc.com/ CompuServe: GO APEX * Internet: sales@apexsc.com 
/\\ = All APEX products come with a 30-day, no-hassle, money-back guarantee. Our free technical support service is among the very best in the industry. 
MyData Control, the MyData Control logo, VBA Companion, and the VBA Companion logo are trademarks of APEX Software Corporation. Visual Basic is a trademark of Microsoft Corporation. Other product names are the properties of their respective owners. 


W09'p1s'pLom@Mawes4004 4/89 6Ez (GOZ) SLY9O 1D uareH 


108 


The FastestDatabase Engine 


Discover CodeBasic: the fastest and smallest 
database engine on the market that's also xBASE 
compatible! You will be able to query hundreds of 
thousands of records in a fraction of a second, or 
add over a thousand records per second. It's 
lightening quick! Check out our features... 


> Multi-user compatible with FoxPro, Clipper and dBASE 
v Tiny DLLs (so it's easy on your system's resources) 

vy f Reader's Choice Award for five consecutive years 

v Full featured powerful report writer included 

o> Scalable to Client/Server » Ly 

vy Royalty free distribution FREE 30 Day % > 


oes “Stee Devel 


SOFTWARE INC 


VI VB Video Trai 


YJ4ON ‘anuaay uojbuiusem Y-rrr ‘suol4njos KGojouyo2| MaN 


iS2H42G02p1\ dNYILOOD GA 499 MAN aIqipasou! 944 YdIM 114 ONIHLON 
Ul vaA Wse9| BuUob no} jj]29 03 -4agoeplA SOldO.L GAONVAGY 2de4-y 943 


aABY Os|e aM ‘puy ‘ade4 yoKs Jo uoWduosap e anigoe4 Kjquedsul 01 ObOZ# 


MARCH 1996 


The application on the 
left was created without 
any source code! 

Use the included data 
aware controls for 
quick formatted data 
entry. Plus, with our 
navigational control, you 
get searching 
capabilities without 
writing a single line of 
code! 


Phone: (403) 437-2410 
Fax: (403) 436-2999 


Q 


M1 


O'VSA 40} S3dV 1 4AY-L N3A3S 


(sodo} 4) ONNVE3HS JIOHM JHL 
SIDUILUES dWVD.LOOS SA #9 -SGNVSNOHL 


adVL L ANV 


quauinoop 4senbe. pue suiyoew y\y4 4nok wou GZzz 6EZ (OZ) 112d 
ANOA SADWAAAA 3949S OMPIA O'y 21SK_ IeNSIA dNVILOOd DA PUL | TS 


GINIVAL 2M “WSN Sy Ul suopPNysU] HAA 153g O44 Aq poyuesaigy 


jjsuosse| padeqoapia FIGYSNAY “AIGVLWAd ay YIM S4zl]OP ONINIVAL 


Y4IM paws Keqeoiap ‘paced 4584 seuss YWYILOOg 18948 ‘AWYS 


9U4 S! S14] jFOPIMU' 


G6'68$ 


(MON 498qxe4 Ano 49949) ISAIMOTVI ALAW ON U4IM “quaquos jeo|uyIeq 


0301 °C AV O.LOOU HA 


(%SL ®ADS) OO'SESS 


Visual Basic Programmer’s Journal 


WINDOWS 
PROGRAMMING 


event log type first, or if you pass an incorrect event log type, the 
LastEventErrorNumber, LastEventErrorSource, and LastEvent- 
ErrorDescription properties are set. 

The OpenAnyEventLog method encapsulates the Open- 
EventLog API call, which takes only two parameters: the server 
name (in UNC format, although the server name itself will work 
if you are already attached to that server) and the type of log. 
That is why you use a Property Let to set the type of log, instead 
of a simple global variable as a property. With Property Let, you 
can check for valid types. Using a blank string for the server 
name opens the log on the local computer. The Open- 
AnyEventLog, if successful, also sets the private variable 
mingEventLogHwd that is used by the other methods and 
properties in this class. 

After opening the log, you have two choices concerning how 
to view the returned event log entries. The first choice is 
whether to filter the returned values. If you want to filter the 
values, set the EventFilter property before calling the 
ReadEventEntries method. If you do not need to filter the 
returned values, just call ReadEventEntries. Note that filtering 
the events will reduce the time for the OLE call, because the 
server’s internal type array is filled with only the filtered records, 
not all the records for that log. 

The second choice is whether you want to read the log 
backwards (latest events first) or forwards. By default the Event 
Viewer applet displays the log backwards, which is also the 
default for the ReadLogForward method (that is, FALSE = 0). 

The EventFilter property has an interesting job—the filter 
itself can bea date/time stamp, along, an integer, or atext string. 
In order to be able to check for valid parameters, the property 
also accepts a filter type parameter. VB does not allow con- 
stants from an OLE object to be exposed (like other OLE objects 
in the Object Viewer). 

Here’s where! get on my soapbox: how does the programmer 
using the OLE object know about these constants, or about the 
properties that he or she must set before calling a particular 
method? The only answer is acomplete help file that youinclude 
with the object. Arguably, the most important part of an OLE 
server is the quality of the included help file. Generally, the 
programmer cannot see your code. He or she can see only the 
public interface. You should include examples to make it easy to 
cut and paste from the help file to the calling application. Think 
of your OLE server as a third-party tool you purchased by mail- 
order—it would be difficult or impossible to use that tool 
effectively without documentation or online help. 


READ IT AGAIN, SAM 

The heart of the program is the ReadEventEntries method 
(see Listing 1), which sets up an array (collection) of all the 
matching event records. At the beginning of the function, set 
the start date—event-log times are formatted in seconds past 
midnight on 01/01/1970—and the time bias, which is the 
difference in seconds between Coordinated Universal Time 
and local time. Actually, the API call GetTimeZonelInformation 
returns the time in minutes, but the private function 
GetTimeBias converts it to seconds, the format the event log 
requires. 

Next, make sure the event log has been opened and use the 
private variable mlngEventLogHwd to ensure you have a 
valid event log handle. The NumberOfEventLogRecords prop- 
erty encapsulates the GetNumberOfEventLogRecords API call. 
Note that at this point the number of records is the number 
of unfiltered records. 

The ReadEventLog call is an interesting exercise in work- 

ing around some of VB’s limitations. The primary problem is 
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the EVENTLOGRECORD structure. Un- 
like most of the API typedefs, this par- 
ticular one can change for each record 
that is read. As a result, declaring a 
Type variable in VB to match the C 
typedef is not possible. However, you 
can read this information with a byte 
array (new to VB 4.0). The CopyMem 
API function then converts the byte ar- 
ray to a string: 
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Public Declare Sub CopyMem _ 
Lib "kernel32" Alias _ 
"RtlMoveMemory" (dst As Any, _ 
src As Any, ByVal Size As Long) 


and the private CVL or CVI functions ex- 
tract any numeric values from that string 
to longs or integers. 

Another programming choice is 
whether to read only one record at atime, 
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or read multiple event records at once. To 
read only one record at a time, set the 
number of bytes to beread (plIngNumBytes- 
ToRead) to less than the length of a single 
record, call ReadEventLog, trap the error 
ERROR_INSUFFICIENT_BUFFER, and re-call 
the function with the number of bytes set 
to plngMinimumBytesNeeded. While this 
works, it is programmatically cleaner to 
read multiple records at one time. I tried it 
both ways, and saw no significant speed 
differences between the two, for either a 
large or a small number of total records. 


DON’T TAKE TOO BIG A BITE 

Note that I arbitrarily set the buffer size 
for a single read to 16K. Setting it to 
higher values may reduce the number of 
cycles in the loop, but may not necessar- 
ily reduce the total time the function 
needs. One big variable (pun intended) 
is the amount of memory installed on 
your NT computer. Feel free to experi- 
ment with various maximum buffer sizes. 
Note that some records may be bigger 
than 16K (thanks to Karl Peterson for 
sending a log indicating the problem—a 
utility called DrWatson can generate sys- 
tem dumps and include them in the log 
entry). In this case, I trap the ERROR_ 
INSUFFICIENT_BUFFER and reset the size 
to the pIngMinimumBytes needed, as | 
explained. 

After getting the records, “trim” the 
byte array to the size of the number of 
bytes actually read (the ReadEventLog 
API function returns only full records) by 
using the plngNumBytesRead return 
value. Byte arrays are hard to work with, 
so use the CopyMem API function to con- 
vert the array into a string. 

The main loop parses the individual 
event records from the multiple-record 
string. Fortunately, after you convert the 
first four bytes of each record string into 
along integer, you have the record length 
of that record. The CVL function uses 
CopyMem to convert the passed string 
(four bytes) into a long integer. Once the 
record length of the first record is deter- 
mined, that string length is isolated into a 
new string for further processing. 

Now that you have the string for just 
one event record, you can process that 
string into the individual elements of a 
type array. The functions CVL and CVI 
convert substrings to long integers or 
integers. The date substring uses the VB 
function DateAdd to add the number of 
seconds from the base timestamp to the 
timestamp returned from the event log. 
The program parses out the Event- 
SourceName and ComputerName by look- 
ing for Chr$(0). The Message string, SID, 
and Data strings are located with the vari- 


ous offset and length values returned by 
the event record. Both SID and Data val- 
ues are converted to hex before being put 
into the type array. 

Actually, the inclusion of system 
dumps in some event logs presents an 
interesting problem. These dumps are 
stored as Data values, and tend to be 
large (12K to more than 16K). Ifthe server 
translates them to hex, it will take along 
time to return to the calling program: 
string concatenation in VB 4.0 is even 
slower than in VB 3.0. Because they are 
already in hex/ASCII format (hex on left), 
the data will be indecipherable. 

As a kludge, you can set the property 
EventDataReturnHex. The default, if you 
don’tsetit, is false. When it’s false, it returns 
the hex values for Data strings that are 256 
bytes or fewer but untranslated values for 
strings of more than 256 bytes. All the val- 
ues I have seen for Data (except for the 
dumps) were displayed as hex in the Event 
Viewer and were 32 bytes or fewer. 

One interesting aside is the EventID. Use 
the EventID as a pointer to the correct 
string to look up in the resource file. Simply 
take the correct four bytes from the record 
and convert them to a long integer using 
CVL. But that number is not the same num- 
ber as appears in the Event Viewer applet. 
In order to get the Event Viewer number, 
you must take only the two low-order bytes 
and convert them into along integer. guess 
Microsoft was concerned with the confu- 
sion that some of the very large numbers 
could create among the users of the Event 
Viewer—so they made it confusing to the 
programmer instead. 


DO WE NEED AN INTERPRETER? 
The Message string is the most compli- 
cated of all the items returned from the 
ReadEventLog API call. The message that 
is returned from the event record is not 
the message that you see in the Event 
Viewer. Most messages contain replace- 
able strings (for example, %/, %2, etc.). 

The private function ResouceString 
encapsulates all the API calls you need to 
return the filled-in Message string. It gets 
the resource name using the passed 
SourceName to look up the full path of 
that resource in the 32-bit registry 
(through a private class module, 
RegistryDB). Any replaceable environ- 
mental parameters such as %System- 
Root% in the returned string are replaced 
with the ExpandEnvironmentalStrings API 
call. The full path is then used to load that 
resource (normally an EXE or DLL). You 
can find the ResourceString function in 
WP0396.ZIP, in the Magazine Library of 
the VBPJ Forum on CompuServe. 

Next, any passed replaceable param- 


Lo 
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eters are parsed into an array, and that 
array is passed to the function Translate- 
Array. This function hides a messy solu- 
tion—the FormatMessage API call will ac- 
cept only a type variable from VB, not an 
array, when you are using the FORMAT_ 
MESSAGE_ARGUMENT_ARRAY bit flag. 
Thanks to Karl E. Peterson and Microsoft 
for this critical piece of information. 


THE EVENT LOG’S 
FUNCTIONALITY IS 
ENCAPSULATED IN AN 


IN-PROCESS OLE SERVER. 
ies EET 


The function FormatMsgFrom-Re- 
sources encapsulates the FormatMessage 
API call. With this one API call, you can 
retrieve the specific message you need 
from the resource (based on the EventID 
from the event record), and replace all 


the replaceable parameters, if any. 

Actually, it’s a little more complicated 
than this, because the algorithm | de- 
scribed doesn’t work for some of the en- 
tries (perhaps 1 percent or so). For these 
event log entries, when you retrieve the 
strings from the resource (used to re- 
place the %1, and so on in the message 
string), those resource strings themselves 
have placeholders in the format %% 1234. 

So, if the returned resource string 
contains any “%%,” that string is sent to 
another private function, Resource- 
String2. In order to find the resource file 
to look up the parameter, in you look at 
the registry again, but with the value 
..\..\Parameter-MessageFile instead of 
..\..\Event-MessageFile. The number im- 
mediately after the %% is used as a pointer 
to get the exact text string from the Pa- 
rameter-MessageFile, just as with the 
original lookup into the Message file, and 
that string is used to replace the % %xxxx 
placeholder. 

Finally, after all the data and strings for 
a particular event record have been re- 
solved, each item is placed in its own ele- 
ment in a type array. Because VB 4.0 does 
not allow you to pass a UDT from an OLE 
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server, the calling program will access each 
of these elements of the type array as a 
property, and pass an index value to indi- 
cate which item in the collection you are 
requesting. Because you're creating your 
own collection, more or less, the indexes 
will run from 1 to the number of event log 
items. Then, go to the top of the loop to 
either read the next event record from the 
already-retrieved byte array, or read an- 
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other set of records into a new byte array. 


CALL IT OUT 

The full code for this column includes a help 
file for the DLL server and an example pro- 
gram. At a minimum, the calling program 
would: 


e Instantiate the object: 
Dim pEventLog As New EventLogs 
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e Set the filter: 
pEventLog.EventFilter(FilterText) = _ 
Filter Type 
° Set the log type: 
pEventLog.TypeEventLog = "Application" 
e Open the log: 
If pEventLog.OpenAnyEventLog_ 
("ServerName") = False Then 
" Get the error information 
e Read the log entries: 
If pEventLog.ReadEventEntries = _ 
False Then 
" Get error information 
e Get a count of the records: 
plngEventCnt = _ 
pEventLog.CountEventRecords 
e Redim a type array to hold return 
values. 
e Loop through the properties (passing 
the index) to fill in the type array. 
e Set the object to Nothing: 
Set pEventLog = Nothing 


You could do several things to im- 
prove the server, but I’ll leave those as an 
exercise for you. It would be nice to add 
sorting as a property of the OLE server. 
Another would be to optimize the 
sublookups for those items that have 
placeholders in the resource string. This 
could be either a very important optimi- 
zation or an insignificant point, depend- 
ing upon the type of log items retrieved. 

Finally, if you are doing multiple look- 
ups with different filters, it would be nice 
to read and store the entire event log 
internally in the server, even on filtered 
items, but return only the items that match 
the filter. Then, another call to the same 
log with another filter could just reread the 
stored items and apply the new filter with- 
out having to reread the log. However, you 
would have to at least check to see if the 
number of items had changed since the 
last time it was called, and reread the 
entire log if a new item had been added. 
You would also haveto comeup withsome 
method to ensure that you had consecu- 
tive index numbers for a filtered string. 

You can find the complete code for 
this project, along with the code for atest 
program to exercise the in-process server 
and a help file, in the VBPJ Forum on 
CompuServe. Search for the file 
WP0396.ZIP. Xl 


Author's Note: Because no installation pro- 
gram is included, you must either manually 
register the DLL with REGSVR32.EXE, or 
compile the DLL again, which will automati- 
cally register the server. In the test program, 
under the References item in the Tools menu, 
uncheck the ReadEventLogs reference. After 
you register the DLL, go to References again 
and check “Read NT EventLogs.” 
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OLE Makes Its Way 


to the Internet 


Glimpse Microsoft’s document- 
centric OLE vision and how 
“Internet OLE” fits into VB’s future. 


by Roger Jennings 


icrosoft’s Internet strategy, outlined last December 7 
by Bill Gates, Paul Maritz, and Pete Higgins, nearly 
caused a meltdown of Microsoft’s World Wide Web 
site. Computer journalists, security analysts, Visual Basic 
programmers, and just about everyone else with a Web 
browser converged on http://www.microsoft.com to down- 
load the technical details behind the public relations hype 
that’s become de rigueur for big-time product announce- 
ments (see Matt Carter’s Interactive Developer column in the 
February 1996 issue of VBPJ for more information about the 
role of Visual Basic in Microsoft’s Internet initiatives). Initial 
dispatches from the computer press concentrated on 
Microsoft’s new cross-cultural ties, such as the letter of 
intent to license Sun Microsystem’s Java programming lan- 
guage and runtime JavaScript, plus the agreement to cross- 
license Oracle’s PowerBrowser OLE control and Microsoft’s 
compact version of VBA, Visual Basic Script (VBS). Bill Gates’ 
willingness to make deals with arch-enemies Scott McNealy 
of Sun and Larry Ellison of Oracle glues a veneer of openness 
to Microsoft’s Windows-centric view of the Internet. Behind 
the scenes, however, Microsoft’s gearing up to make OLE 2.x 
the backbone ofits Internet and intranet strategies. Today, 70 
to 80 percent of all Web browsers run under Windows 3.x and 
Windows 95. Microsoft clearly intends to make OLE the 
linchpin of their efforts to protect Windows’ market position 
against impending competition from the likes of Oracle’s 
$500 “Network Computer” and similarly priced diskless con- 
sumer PCs based on Apple’s new Pippin architecture. This 
month’s column gives you the big picture of Microsoft’s 
document-centric OLE vision and how “Internet OLE” fits into 
the future of Visual Basic and its Internet derivative, Visual 
Basic Script. 


Roger Jennings, a principal of OakLeaf Systems, is a consultant 
specializing in Windows client/server database front ends. He has 
more than 25 years of computer-related experience, and is the 
author of four programming books: Using Access 95, Special 
Edition, and Discover Windows 3.1 Multimedia for Que Books; 
and Access 95 Developer’s Guide and Database Developer’s 
Guide with Visual Basic 4 for Sams Publishing. He’s also the 
coauthor with Peter Hipson of Sams’ Database Developer’s Guide 
with Visual C++ 4. Roger’s now in the process of writing Using 
Windows NT Server 3.6, Special Edition, and Using Windows 
Desktop Video, Special Edition, for Que. Reach him by CompuServe 
at 70233,2161 or on The Microsoft Network as Roger_Jennings. 


MICROSOFT PLAYS A FAST GAME OF CATCH-UP 
Microsoft may have missed the first boat to the Internet, but that 
doesn’t mean that Bill Gates and Co. aren’t up to snuff on the 
technology side. Despite the accolades heaped on Java by the 
computer and business press, Microsoft’s no stranger to the 
downloadable objects business. For example, Microsoft Interac- 
tive TV (demonstrated at the National Cable TV Association’s 
Cable ’95 conference in mid-1995) is based on a distributed 
version of COM, the Component Object Model that’s the founda- 
tion for OLE 2.x (see my Interactive Developer column in the 
October 1995 issue of VBPJ for more information on OLE and 
MITV). MITV servers provide class stores for downloadable 
executables and DLLs, and object stores for networked OLE 
components to support interactive TV set-top boxes. The 
Microsoft/Visa Secure Transaction Technology (STT) for Internet 
commerce first appeared as a component of MITV. The 
whitepaper, “Microsoft Interactive Television in Detail,” printed 
for the Cable 95 show, proposed Visual Basic and Visual C++ as 
alternative programming languages for the applications layer 
for set-top boxes. Microsoft announced at its Interactive Media 
Conference in mid-July 1995 an Internet version of its Blackbird 
authoring tool for The Microsoft Network that incorporates VBA 
and supports OLE controls. So, much of what Microsoft an- 
nounced at its December Internet Strategy Workshop was al- 
ready in the works at Redmond. Microsoft’s objective now is to 
accelerate moving the distribution medium from MITV and MSN 
to the Internet. 

Microsoft’s catch-up plan involves these basic browser-side 
components: 


¢ Win32 Internet client WinInet functions in WININET.DLL. 

¢ Document Objects for creating Internet-enabled OLE servers 
and containers. 

¢ OLE Scripting with VBS (and Java/JavaScript) for embedded 
programming in HTML documents. 

¢ OLE controls for customizing HTML documents and adding 
browser capability to applications. 

¢ Progressive rendering of JPEG graphics. 

¢ ActiveVRML for 3-D animation. 

¢ Internet Studio (the new name given the Internet version of 
Blackbird), a “visual publishing” tool for developing World Wide 
Web content. 

¢ A proposed “digital signature” system to verify the integrity of 
executable applications and objects distributed over the Internet. 


The Win32 API for Internet client applications is called 
Sweeper SDK. When this column went to press, the Sweeper SDK 
included documentation for WinInet and OLE Document Ob- 
jects DocObjects), plus ademonstration application ofasample 
Framer application that hosts DocObjects. You can read the 
current lowdown on the Sweeper SDK and download the Framer 
demo app at http://www.microsoft.com/intdev. 

On the server side, Microsoft Internet Information Server 
(formerly Gibraltar), Merchant secure transaction server, 
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Figure 1 | Documents ina Bind. Microsoft Office 95’s Binder is a DocObject container that supports all of the primary features of version 


A 


1.0 of the OLE Document Object specification. Web pages that act as DocObject containers can incorporate objects supplied 
by DocObject-compliant OLE 2.x servers. Substitute a tree view of local and networked folders for the row of icons and you have a future 
version of Explorer that activates objects in its own DocObject container pane. 


Internet proxy/firewall server (code-named Catapault), and 
Media Server (code-named Tiger) are scheduled to become 
components of BackOffice during the first half of this year. Bill 
Gates announced in his kickoff speech at the Internet Strategy 
Workshop that Media Server will be adapted to deliver video 
and audio over the Internet. Microsoft and Process Software 
Corporation, a Web server ISV, are cooperating on the Internet 
Server API (SAPD, which extends the Internet Information 
Server for commercial applications and system administration. 
A future version of ISAPI will include ODBC extensions for 
database connectivity. Version 1.0 of the Internet Information 
Server should be released as a standard feature of Windows NT 
Server by or shortly after the time you read this column. 
Publishing limitations prevent full coverage of all of these 
forthcoming products, so I'll concentrate on the components 
that primarily are designed to support and extend OLE 2.xin the 
Internet and intranet environments. 


STANDARDIZE INTERNET ACCESS WITH WININET 

WININET.DLL (WinInet) is a 32-bit add-on Sweeper library that 
provides operating system support for client-side Internet func- 
tionality. It’s a good bet that the future Internet-enabled ver- 
sions of Microsoft Office 95 will make extensive use of the 


WinInet functions. Initially, Microsoft is making WinInet avail- 
able to developers as a distributable add-in for Windows 95 and 
Windows NT 3.51+; WinInet will be incorporated in future ver- 
sions of Windows 95 and Windows NT. The primary objective of 
the library is to eliminate the need to deal directly with TCP/IP, 
Internet protocols (such as FTP and HTTP), and Windows 
Sockets. WinInet includes ANSI and Unicode versions of 
Internet..., Ftp..., Gopher..., and Http... functions that support re- 
entrancy for creating multithreaded applications. Many of the 
WinInet functions will replace a substantial amount of C pro- 
gramming now required to implement routine tasks, such as 
scheduled retrieval of files from an FTP server or automatically 
gathering daily information from a specific set of Web pages. 
Application programmers can use WinInet functions to inte- 
grate Internet functionality within Windows productivity appli- 
cations. You can download the preliminary specification for 
WinInet as http://www.microsoft.com/intdev/inttech/ 
docobj.htm. 
The basic WinInet functions include: 


e InternetOpen, which returns a HINTERNET handle. 
e InternetConnect, which opens a connection to a specified 
server. 
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¢ InternetOpenUrl, an alternative to 
InternetConnect; it begins reading aspeci- 
fied HTTP, FTP, or Gopher site. 

¢ InternetReadFile, which fills a buffer 
with content. 

¢ InternetWriteFile, which writes datafrom 
an FTP server to a buffer. 

e InternetGetLastResponselnfo, which 
handles errors. 
¢InternetSetStatusCallback, which provides 
information for display in a status bar. 

¢ InternetCloseHandle, which closes an 
HINTERNET handle opened by 
InternetOpen, InternetConnect, or 
InternetOpenUrl. 


HttpOpenRequest and HttpSendRe- 
quest deal with specific HTTP headers. 

Visual Basic developers can declare 
WinInet function prototypes arid use all 
but the callback functions in conventional 
VBA code, but it’s likely that OLE controls 
with hooks to appropriate WinInet 
Internet..., Http..., Ftp..., and Gopher... 
functions will be available to simplify Vi- 
sual Basic 4.0 and Access 95 Internet pro- 
gramming. An alternative is to write a 
simple in-process or out-of-process OLE 
server with Visual Basic 4.0 or, prefer- 
ably, Visual C++ 4.0 to provide an OLE 
wrapper around WinInet for retrieving 
Web pages or files. It shouldn’t surprise 
anyone that all of Microsoft’s Internet- 
related additions are 32-bit-only. Microsoft 
is giving away the bulk of its Internet 
technology, so recouping the Internet in- 
vestment depends on increased sales of 
Windows 95, Office 95, and Windows NT. 


CREATE COMPOUND BROWSERS WITH 
DOCOBJECTS 

OLE DocObjects began life as the propri- 
etary technology behind the Microsoft 
Binder included in Office 95. Allmembers of 
Microsoft Office 95 (except Schedule+) and 
Visio Corp.’s Visio 4.0 are DocObject serv- 
ers. Binder is an enhanced OLE 2.1 
DocObject container that can handle mul- 
tiple objects, called Sections. Unlike Visual 
Basic’s OLE 2.0 OCX, Binder supports mul- 
tiple views of an object within a Section (see 
Figure 1). For example, in Binder you can 
view embedded documents in Word 95’s 
Normal, Outline, Page Layout, and Master 
Document mode; Visual Basic’s OLE 2.0 
OCX limits you to Word's Page Layout view 
unless you open Word. The reason for this 
limitation is that the frame of the OLE 2.0 
OCX is foreign to the server. That is, Word, 
Excel, PowerPoint, and other OLE 2.x serv- 
ers don’t “own” the frame in which to dis- 
play an embedded document. Lack of own- 
ership contributes to difficulties displaying 
the server’s frame adornments, such as 
scroll bars, workbook tabs, and toolbars 
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Figure 2 Automate OLE Objects in Your Web Browser. The Microsoft OfficeBinder 

1.0 type library exposes the Sections collection. Each Section object represents 

an embedded DocObject, which exposes as the Object property a pointer to the document's 

server; you use HTML-embedded Visual Basic Script code to manipulate the server's 

Application object. The object structure of Web pages you create with Internet Studio is 
expected to be modeled on Microsoft Binder. 


within the container. These problems limit 
the utility of VB4’s OLE 2.0 OCX with com- 
plexembedded objects, suchas Excel work- 
books. DocObjects abstract views, so that 
theserver owns thecontainer-supplied view 
frame (for adornments) and the document 
content view within the container. Com- 
pare the behavior of a Word or Excel Sec- 
tion ofa binder with the same Word or Excel 
object embedded in the OLE 2.0 OCX or 
inserted into a Visual Basic form to see the 
viewing improvements offered by activated 
DocObjects. It wouldn’t betoo surprisingto 
see a 32-bit DOCOBJ32.0CX (or whatever) 
control for Visual Basic 4.0 and Access 95 
developers “real soon now,” plus forms 
that fully support insertable DocObjects in 
a future version of Visual Basic. 
DocObjects are likely to be one of the 
primary mechanisms Microsoft uses to 
Internet-enable the next version of Office 
applications demonstrated by Bill Gates 
at the Internet Strategy Workshop. 
DocObject servers support OLE “abstract 
storage technology,” which lets you save 
the data of multiple objects as a single 
entity; in the case of Binder, the persis- 
tent storage is a FILENAME. OBD, an Office 
Binder data file with an Office.Binder.95 
association in Windows 95’s Registry. 
(Binder also supports OBT template and 


OBZ wizard file extensions.) Abstract stor- 


age and moniker binders let DocObject 
containers activate linked files in place. 
Binder is an OLE Automation server with 
an OfficeBinder 1.0 type library to which 
you can create a reference in any VBA- 
enabled application, then create new or 
manipulate existing Binder Section ob- 
jects (see Figure 2). Any non-trivial 
DocObject container is expected to ex- 
pose its objects for manipulation through 
OLE Automation calls from VBA or VBS. 

The Internet gets the most press atten- 
tion, but enterprise-wide intranets are 
likely to generate the greater short-term 
revenue for Visual Basic developers, con- 
tent designers/editors, and networking 
VARs. When you implement an intranet, 
users will expect to be able to use their 
browser to seamlessly view all of the docu- 
ments to which they have access, not just 
documents that have been created in or 
converted to HTML. If you implement 
DocObject container features, you can 
provide a Web browser that not only dis- 
plays Web pages in conventional HTML 
format via WinInet, but also lets the user 
browse documents created by DocObject 
servers that are stored as local or net- 
worked disk files through Windows’ file 
functions. Instead of a link to a URL, you 
open the persistent storage file that holds 
the object’s data from a folder. Depend- 


116 MARCH 1996 Visual Basic Programmer’s Journal 


Your IDE and software configuration 


_ management- 


Together at last. 


Imagine never having to leave your Visual Basic environment for your 
software configuration management (SCM) needs. Built in SCM leverages 
team productivity, eliminates wasted time, and streamlines the entire 
development process. And best of all, your developers have tools 
that work together seamlessly so SCM is a productivity boost—not a 
productivity obstacle. 

MKS Source Integrity fits seamlessly into your favorite development 
environment. 

With MKS Source Integrity, you finally have a software configuration 
management system that integrates with your Visual Basic IDE. MKS 
Source Integrity’s rich feature set including sandbox™ environments and 
projects, prevents developer collisions, overwriting and duplication of 
source changes. Labeling and promotion facilities allow managers to 
define key stages throughout the development lifecycle, including design 
and post-release maintenance. 

You'll cut hours by never having to leave your native Visual Basic IDE. 
MKS Source Integrity is the most comprehensive configuration manage- 
ment system available today designed to maximize your team-based 
development. More than 45,000 developers use MKS Source Integrity’s 
complete suite of tools to help them increase productivity, protect 
software assets, and guarantee overall source code integrity. 


To find out how MKS Source 
Integrity can accelerate your team’s 
development, call today for your 


Our challenges are your challenges. All people depicted in 
this ad are MKS personnel. 


MKS, MKS Source Integrity, and Sandbox environments are registered trademark of 
Mortice Kern Systems Inc. (MKS). All other trademarks are acknowledged. 


NEW RELEAST 


“Would you like to know how MKS Source 
Integrity integrates... 

One word: ; 

- LAN Times, August 95 


Source Integrity gives you complete 
hooks into leading development 
environments including: 

* Delphi 

* Borland C++ 

* Microsoft Visual Basic 

* Visual C++ 

* PowerBuilder 


Call today to order MKS Source Integrity 
or to receive your evaluation copy. OR 
download it from our web site. 


1-800" 265"2797 
185 Columbia Street West 
Waterloo, Ontario N2l 5Z5 
Canada 
MORTICE KERN SYSTEMS INC. Main: (519) 884-225! 


MKS Germany: +49 711 16714 0 
MKS UK: #44 171 624 0100 
MKS Scandinavia: +45 3325 6555 


INTERACTIVE 
DEVELOPER 


lAdviseSink 


10leContainer 


10leClientSite 


10leDocumentSite 


I0leInPlaceSite 


IContinueCallback 


10leInPlaceFrame 


10leCommandTarget 


10leInPlaceUIWindow 


I0leInPlaceObject 
IOleInPlaceActiveObject 
IDocumentView 


IPrint 
10leCommandTarget - 


interfaces associated with 
OLE 2.0, providing ameans of 
manipulating server views 
within the container. Conven- 
tional OLE2.0 containers have 
object, ratherthan document, 
views; thus printing docu- 
ments that include headers, 
footers, footnotes, and other 
appurtenances presents dif- 
ficulties. DocObject’s 
IOleDocumentView, [Print, 
and IContinueCallback inter- 
faces are intended to solve 
such printing problems. 
DocObjects also support 
“menu merging,” a more el- 
egant method for grafting the 
server’s menu structure to 
thecontainer’s menubar. The 
Framer demo app, described 
in Kraig Brockschmidt’s http:/ 
/www.microsoft.com/intdev/ 
inttech/framer.htm, imple- 
ments the basic features of 
a DocObject container, but 
doesn’t print the document. 

According to Doug 
Heinrich, Microsoft’s direc- 
tor of developer relations, 
Internet Explorer 3.0 will 
become a container for OLE 
objects, as well as conven- 
tional HTML documents. 
DocObjects obviously will 
play a major role in 
Microsoft’s new browser, 
which Heinrich says should 


FIGURE 3 Just What You Wanted: More IOle... Interfaces. DocObject containers for viewing 
DocObject-enabled documents must support at least the new IOleDocumentSite interface 

(red); IOleCommandTarget and IOleContinueCallback interfaces are optional (red italic »). DocObject 
servers require implementation of IOleDocument and IOleDocumentView (red); IPrint and 
IOleCommandTarget are optional (red italic). Both the container and server must provide the standard 
OLE 2.0 interfaces for in-place activation. (This diagram is based on the early release of Microsoft’s OLE 


Document Objects Specification, version 1.0.) 


ing on your file privileges or the version of 
the browser in use, you can view, modify, 
add, and/or delete the objects, including 
Web pages. Sharing an Excel worksheet 
for budgeting definitely beats filling ina 
conventional HTML form and using a Com- 
mon Gateway Interface (CGD script to 
handle the resulting data. A DocObject con- 
tainer with an Explorer-type interface would 
substitute a tree view of the local and net- 
work drives for the Section icon pane of 
Binder. (Bill Gates demonstrated a proto- 
type DocObject container of the Explorer 
class at the Internet Strategy Workshop.) 
Another advantage of DocObjects is the 
ability to specify key words and other prop- 
erty values for searching; there’s no equiva- 
lent of the Internet Information Server’s 
Internet Fast Find feature in today’s defini- 


tion of HTML. Users won’t need the suite of 
Office 95 apps to view embedded 
DocObjects; Microsoft promises a free 
DocObject-compatible viewer for viewing 
(but not editing) embedded documents. 
Before its Internet Strategy Workshop, 
Microsoft published an early release of the 
specification for OLE Document Objects 
(version 1.0, November 27, 1995). You can 
obtain the current version of the specifica- 
tion as http://www.microsoft.com/intdev/ 
inttech/docobj.htm. The specification enu- 
merates the new [Ole... and other I... inter- 
faces that implement DocObjects: 
IOleDocument, IEnumOleDocumentViews, 
IOleDocumentView, IOleDocumentSite, 
IPrint, IContinueCallback, and 
IOleCommandTarget (see Figure 3). These 
interfaces supplement the existing IOle... 


be available about the time 
you read this column. Doc- 
Objects reflect Microsoft’s 
transition from conven- 
tional object orientation to 
the document centricity of 
the World Wide Web. Re- 
lease of a preliminary but 
detailed specification for DocObjects is 
part of Microsoft’s program to convince 
competing browser publishers to adopt 
OLE 2.x in their Windows offerings. The 
timing of publication of the DocObjects 
specification also may have been influ- 
enced by Apple Computer’s announce- 
ment of a related approach to adding 
Internet connectivity to desktop apps 
through Cyberdog, which is based on 
OpenDoc object technology. 


VISUAL BASIC SCRIPTS AND OLE SCRIPTING 

Microsoft offers Visual Basic Script as an 
alternative to Sun Microsystems’ nascent 
JavaScript for interactive Web-page 
authoring. Microsoft describes VBS as “a 
high-performance scripting language de- 
signed to create active, online content on 
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the World Wide Web.” Microsoft intends to propose VBS to the 
World Wide Web Consortium (W3C) and the Internet Engineer- 
ing Task Force (IETF) as “an open Internet scripting language 
standard” and will post a “source reference implementation” on 
the Internet. According to Microsoft’s press release for VBS, 
there are more than 3 million developers creating Visual Basic 
and VBA applications. The claim that one in 50 of the purported 
150 million users of Windows is a “developer” may be over- 
stated, but there’s no question that Visual Basic and VBA 
predominate in the Windows programming tools and productiv- 
ity application scripting business. Clearly, Visual Basic develop- 
ers and Microsoft Office power us- 
ers will prefer programming inter- 
active Web pages in a subset of 
VBA rather than creating their own 
objects with a new language, such 
as Java or JavaScript, derived from 
C++. Bristol Technology Inc. and 
MainSoft Corp. have announced 
their intention to port VBS to sev- 
eral flavors of Unix, and there’s 
sure to be a version for Mac users, 
too. Thus there’s little doubt that 
WSC and IETF ultimately will sanc- 
tion both JavaScript and VBS in the 
form of Internet RFCs. 

OLE Scripting is Microsoft’s 
mechanism for incorporating VBS 
and other scripts within DocObjects. 
A script is defined as “some executable blob” that can be source 
codein text format, compiled pseudo-code, or executable machine 
code. When a Web browser with OLE Scripting detects that a blob 
of script is incorporated in a compound Web document (called a 
project), the browser initializes the particular script engine, such 
as VBS or JavaScript, to process the script. The script engine is an 
in-process server (OLE DLL) and you must register it with a unique 
CLSID, plus its name in\HKEY_CLASSES_ROOT\ScriptEngine 
\<Name> in the Registry. After an initial interchange of data be- 
tween the browser and the script engine, the engine starts and 
captures events triggered by controls (called projectitem objects) 
contained in the equivalent of a Visual Basic form (a class object). 
To implement this process, the script engine exposes Scripting 
(new) and IPersistStorage interfaces. IScriptingSiteis implemented 
onthe application (project) side to resolve the names of objects to 
their instances. The IGangConnectWithDefault interface is respon- 
sible for resolving the handling of events triggered by project item 
objects. OLESCRPT.HTM, available from http://www. 
microsoft.com/intdev/inttech, provides a preliminary description 
of the new OLE interfaces required to implement OLE Scripting. 

Microsoft states that client-side VBS will enable Web page 
authors using Internet Studio “to link and automate a wide 
variety of objects in Web pages, including OLE objects and 
‘applets’ created using the Java language.” So, VBS will include 
features requried for OLE Automation programming. 
Microsoft’s “Visual Basic Script: Visual Basic Comes to the 
Net” white paper (VBSINTRO.HTM, also available from http:// 
www.microsoft.com/intdev/inttech) provides the following 
HTML example for a VBS source code blob that interacts with 
an OLE control and a Java applet embedded in a DocObject 
Web page: 


<Insert> 
clsid = {"Insert class ID here"} 
OLEcontrol.Forecolor = True 
OLEcontrol.Animate 


MICROSOFT MAY HAVE 
MISSED THE FIRST BOAT TO THE 
INTERNET, BUT THAT DOESN'T MEAN THAT 
BILL GATES AND CO. AREN'T UP 10 SNUFF 


ON THE TECHNOLOGY SIDE. 
ss ae aa 


JavaApplet.Forecolor = OLEcontrol.Forecolor 
</Insert> 


Achieving the objective of a “compact, high-performance” 
VBS requires considerable streamlining of the feature set of 
today’s VBA implementation to reduce the size and complexity 
of the VBS interpreter. Based on Microsoft’s preliminary “Visual 
Basic Script: Working Description” white paper of December 13, 
1995 (VBSCRIPT.HTM), VBS doesn’t offer all of the functionality 
of VBA, but it’s reasonably certain that the utility of VBS within 
the HTML environment will at least match that of JavaScript. On 
the server side, you can choose be- 
tween full-fledged Visual Basic and 
VBS for handling chores such as 
registering Web visitors in a data- 
base, delivering database content, 
and other heavier-duty operations, 
probably in conjunction with ISAPI. 
The advantage of ISAPI over CGI is 
that ISAPI functions offer improved 
performance by running in-process; 
CGI operations run in their own pro- 
cess space. 

Web pages created with Internet 
Studio are OLE control containers, 
so you'll be able to incorporate 32- 
bit OCXs, in addition to DocObjects 
created by Office applications. The 
OLE Controls 96 specification 
(OCX96.HTM) adds several new features required to optimize 
OLE controls for use in Web pages. Sun Microsystems has 
announced a forthcoming Java OLE control that incorporates 
the Javaruntime engine, allowing incorporation of Javaapplets 
within DocObjects for the Web. The Java OLE control, sched- 
uled for release in the second quarter, eliminates the need to 
implement OLE Scripting, at least for Java code. (If your Regis- 
try is amess now, just wait until you download and register for 
OLE Scripting a bunch of Java and/or OLE objects from each of 
your favorite Web sites.) 

One by-product of the emergence of Java for creating 
downloadable applets may be broader acceptance of inter- 
preted languages by the programming community as a whole. 
Assuming a runtime interpreter of reasonable size, down- 
loading p-code for an applet is much more efficient than 
retrieving a self-contained executable file. The “Interpreted 
and Dynamic” chapter of Sun Microsystems’, “The Java Lan- 
guage Environment: A White Paper,” available as http:// 
java.sun.com/whitePaper/java-whitepaper-7.html, makes 
Sun’s case for interpreted, rather than compiled, program- 
ming languages. Visual Basic developers clamoring for a 
native Visual Basic compiler might want to read the chapter 
and then rethink their position, at least as to Internet-related 
applications. 

December 1995 was a very interesting month for Visual 
Basic programmers, purveyors of Internet-related products, 
and investors in high-tech firms that depend on the Internet 
for the future earnings that justify today’s high-flying stock 
prices. The first half of 1996 will determine if Microsoft’s OLE- 
and VBS-based Internet initiative is destined for short-term 
success. Bill Gates said on December 7, 1995, “We’re hard- 
core about the Internet. Anything we’re focused on we’re 
generally hard-core and we are focused on this and therefore, 
very hard-core.” Microsoft’s total dedication to OLE and big- 
time investment in OLE for the Internet ensure that OLE 2.x 
and VBS will be major components of future Web browsers. &! 
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VISUALBASIC Product Showcase 


Your Showcase For 
Programming Tools 


This special advertising section 
highlights tools designed specifically 
for Visual Basic programmers. If you 
are interested in placing an ad in this 
section, please call 800-848-5523. 


Unique Custom Controls 


We've got the controls everyone else missed. 
Why buy yet another package with a bound 
list box when you can get more? Our 
controls are easy-to-use, solid, and royalty 
free. There are too many to mention here, 
so write, call, or fax us for a product list 
and a free sample disk. 


High Speed 
Charting 


This disclaimer covers all trademark 

j| references in this section. Advertisers 

O}S} recognize the trademark rights of other 

SB) vendors. Specifically, QuickBasic and 
Visual Basic are trademarks of 

Microsoft Corporation. PowerBasic is a 

trademark of Spectra Publishing. True Basic 

is a trademark of True Basic, Inc. 


Mabry Software 
Post Office Box 31926 
Seattle, WA 98103-1926 
TELE:(206) 634-1443 FAX:(206) 632-0272 
BBS:206-634-0783 CIS:71231,2066 


LabOBJX Real-Time Chart™ 

e Visual Basic custom control for fast 
real-time charting ¢ Oscilloscope and 
strip chart display modes ¢ Interactive 
displays without writing any graphics 
code ¢ Flexible input data formats 

e Easily customize look and feel with 
extensive set of properties * Multiple 
numeric scales and labels on axes and 
frames ¢ Supports Visual Basic, C++, and 
Delphi ¢ $199 


SECURE DESKTOP 


Shell replacement provides everything 
necessary to lock down a public computer. 
Password protect icons, trap Ctrl-Alt-Del & 
task switching keys, schedule by time & 
event, disable multiple instances, and even 
disable other application’s menus. Great for 
laboratories, classroom settings, factory 
automation, and information kiosks! 


Export Library 


DataExport/DLL lets you output over 30 
spreadsheet and database formats, 
including Access, Excel, dBase, Paradox, 
1-2-3 and Quattro. Call for free demo, 
email de-vbpj@spaldingsoft.com or visit: 
CompuServe (GO SPALDING, Lib 2), 
http://www.spaldingsoft.com 

$795 NO ROYALTIES VISA/MC/AX 


SPALDING SOFTWARE, INC. 
154 Technology Parkway, Suite 250 
Norcross, GA 30092-2911 USA 
TELE:(770) 449-0594 FAX:(770) 449-0052 


Scientific Software Tools, Inc. 
19 E. Central Avenue 
Paoli, PA 19301 
TELE:(610) 889-1354 FAX:(610) 889-1556 
E-Mail: sales@sstnet.com 


Visual Automation, Inc. 
TELE:(517) 622-1850 FAX:(517) 622-1761 
dfahey @voyager.net 
http://www. voyager.net/ 
visualautomation/vahome.htm 


ZIP Data Compression 


New DynaZIP 3.0 Data Compression 
Toolkits for Windows let your app’s 
read/write standard ZIP files easily, 

quickly, reliably! Royalty-free VBXs, 
OCXs, and DLLs support encryption, 
spanning, recurse, and more. 30 day 
no-risk guarantee, fully supported, 
only $249 (16-bit) or $299 (32-bit). 


—.| Bar Codes from 
4 a = 
Bar Code Trail Visu al Basic™ 


File HotKey Metafile options Bit 
-Barcodeype—| OF from any font based 
Ocede3s ©| Windows program using 


Oracsa ©)! BarFont™ for Windows™ 
Ol2085 © 


OCodabar Of This is a program to print bar codes using 
O Code 128 ©} bitmaps, metafiles, or TrueType fonts on 
-Variations ——| dot matrix, LaserJet, and DeskJet printers. 
include humant 4 DLL is furnished for printing from within 
~ VB or other languages. $199 list price. 
Special Application Inclusion pricing available for developers. 


File Edit 
Tale text, spread 
DYRYN and tum i 


1 23456 


Inner Media, Inc. 
60 Plain Road, Hollis, NH, USA 03049 
TELE:(800) 962-2949 or (603) 465-3216 
FAX:(603) 465-7195 


) 7 Also Available: Direct from the Manufacturer/Developer 
Developer s Kit e Menu Driven Labeling Software 30 Day Money Back Guarantee 
Don’t spend time re-writing already written ¢ Bar Code Readers (attach to kybd) 800 Technical Support 
code. Network-ready management system ¢ Portable Bar Code Readers Free UPS Blue Shipping in the USA 
developer kits easily modified to fit your e Laser Scanners, Wands, and CCDs Reseller Inquiries Invited 
exact needs. G/L, A/P, A/R, Payroll, Bank e Cordless Radio Frequency Readers All Items in Stock and Shipped the Same Day 
Manager, Inventory, Point of Sale and ¢ Thermal Transfer Label Printers Call for our Free 28 page Color Catalog 


Order entry modules available. Call for 
pricing and demo availability. 


0 THI T Worthington Data Solutions 
3004 Mission Street 
/ORTHINGTON Santa cae CA 95060 


TELE:(800) 345-4220 or (408) 458-9938 
DATA SOLUTIONS FAX:(408) 458-9964 


Bayou City Systems, Inc. 
8535 Triple Crown Dr. 
Houston, TX 77071-2434 CIS:74511,2041 
TELE:(713) 777-3736 FAX:(713) 777-3746 


Basie Product Showcase 


Productivity Breakthrough With ScionZ™ 


Cut your development effort in half with ScionZ; 
Cony break through to the future of programming. 


: GRAPH OF Oil-Water Separators For data; Path= C:\SCIONZ 
File Edit Graph ScionZ 


Selected [SCFM 


(Seeeticsions]  [[Rasiecisentetenene] Poe ScionZ are data objects, just like variables or records. While 
[Compressor Type | variables were invented for scientific programming, and records 
[Reciprocating were developed for magnetic tape storage, ScionZ are designed for 


[ Compressot Lubrication Type | PC programming and disk storage, and are used instead of records 
[pfienenission.Motorom |] [vpaiaute Minerat Oa] [yah taba oa and variables. 

Programming is dramatically simplified. Your information on disk 
is the same as your information in memory. A stand-alone ScionZ 
viewer enables you to develop your data structure independently. 

A scion has a name, a parent, and zero or more children. The 
name is up to 64,000 characters. Saving a scion to disk saves its 
descendants, their descendants,...the whole family. Loading, 
copying, or deleting a scion affects its entire family. 

Available for VB3! Free upgrade to VB4 in June, 1996. Introductory 
special price of $235.00 will pay for itself in your first week. Written 
in VB3, source code included. No runtime license fee, 30 day 
money-back guarantee. 


Text of Instructions For Help 


#) Select compressor type and 
compressor lubricant type 

2) Select model 

3) In the Input Quantities panel, 

enter quantities sufficient to 

meet your capacity needs. 

Total capacity and total price 


are shown in that panel. 

4) Click the CONTINUE button 
to place these items in the 
quote 

click HELP for additional info. 


jamentin| 681496 | 17.7 


681498 | 


NG ee 
~— 
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7; X . 5 
é \ Configuration Systems 
S 585 Bair RoadBerwyn, PA 19312 
TELE: 800-610-5066 FAX: 610-644-5944 


SCAN TOOLS" Speech 


Recognition 


The ULTIMATE User-Interface 


Easily and rapidly develop reliable state-of- 
the-art speech enabled applications using your 
favorite windows development tools, Visual 
Basic, Delphi, C++. 


e BARCODE RECOGNITION 
in .05 seconds for on-line indexing. 


e BARCODE WRITING 
into an image buffer. 


CustomVoice v2.1 is the only desktop 
Speech Recognition Custom Control that 
enables you to develop reliable, high performance speech enabled applications that are 

° Speaker-Independent ¢ Continuous-Speech * Software-Based and ¢ Grammar-Constrained. 
Custom Voice comes with a whole set of tools, including ¢ Interactive Debugger * Parser APIs 
e Sample Applications and more. New version makes it easier than ever! Buy the complete 
Speech Recognition Development Bundle now for a special price of only $695. 


e NOISE REMOVAL 
from BITONAL image buffer. 


e SKEW DETECT & CORRECT 
improves OCR results. 


e LINE REMOVAL 
for processing of forms. 


CustomTelephone v1.0 works like CustomVoice, it also enables telephony/voice response 
applications with similar Speech Recognition capabilities! It’s not like other systems that 
provide recognition of only simple digits, “Yes” and “No”. Empower your existing applica- 
tions such as ¢ Voice Mail ¢ Data Entry/Retrieval and * Phone Banking with voice 
activation and control! Works with major voice response boards, such as Dialogic. Software 


e TIFF read/write, 
Scale, CCITT De-/Compress. 


bundle is only $995. 
Axtel, Inc. 

18255 Mt. Baldy Circle 
Fountain Valley, CA 92708 
TELE:(714) 964-6666 FAX:(714) 964-6766 
Free Demo on http://www.axtel.com 


TELE:(617)492-0120 FAX:(617)427-3625 


Yt & G Graphics Tutepace Tue. customve@world.std.com 


CIS:74754,1517 or 74774,273 GO SPEECH 


VISUALBASIG Product Showcase 


VB4 FAST TRACK TRAINING 


“New Features of VB4” covers VBA, 

Objects, OLE Servers, etc. “Designing a GUI 
Interface” teaches you to use VB for 
prototyping and user interface design. 
“Survey of VB Tools” gives you pros and 
cons of various third party tools. Seminars 
and self-study kits available. 


Grace Technology Institute, Inc. 
TELE:(508) 650-3939 
FAX:(508) 655-4066 

gracetec@world.std.com 


New DDE OCX 


Overcome the limitations of using DDE in 
Visual Basic with the new version of RTList. 
RTList 2.0 lets you easily retrieve large 
quantities of real-time data from any DDE 
server. Works especially well with: 

¢ Financial market datafeeds e.g. Reuters, 
ILX, ADP ¢ Automation and process 
control data. Fully functional server VBX 
included. $495. No royalties. 30 day MBG. 


XYRIS Software, Inc. 
TELE:(212) 925-4388 FAX:(212) 925-4929 
71052.3172@compuserve.com 


CERTIFICATION 
WOSSA-Ir-CERT™ 


WOSSA-I-Cert gives timed simulations of 

the MS Windows Architecture I exam. 

¢ Pinpoints your weak areas & explains 
the reasoning behind the answers. 

e Includes study outline. 

¢ Money Back If You Don’t Pass Guarantee. 

WOSSA-I-Cert, WOSSA-II-Cert, VB-Cert 

and AccessCert $129 each. 

THE DEVELOPER PAK (All 4) $399. 

Also available: NT-Cert/NT-ServerCert 

$149 each, Pair $249. Examinator (Win 

3.1), WordCert (Word Exam) $89 each. 

NetCert (Networking Basics) $149. 

Add $4 s&h Visa/MC/Amex/Check. 


Transcender Corporation 
242 Louise Ave. Nashville, TN 37203 
TELE:(615) 726-8779 FAX:(615) 320-6594 


Visual Help Pro cites) 7 + , | 
=== Visual Help Pro 
| tesor ene Finally...Professional Help files are 


just a click, drag and drop away! 


Utilizing the ease of drag and drop 
EONS Visual Help allows you to create 
Sea | impressive professional help files. 


Zo Deate Pretsce Toe 


WYSIWYG help development and runtime testing environment. 

¢ Drag and Drop Titles, Headings, Paragraphs, Jumps, Popups and Buttons. ¢ Support for 
Tables, Bullets and Numbered lists. ¢ Graphically define secondary Windows and non- 
scrolling regions. ¢ Play Multimedia WAVE, MIDI and Video-for-Windows AVI files. 

¢ Support for calling Windows 3.1 help Macros. ¢ Automatic generation of Glossary and 
Index sections for your help file. ¢ Automatic or manual assignment of help topic’s context 
ID’s. ¢ Generates user manuals from your help files. ¢ Built-in spell checker. 

¢ Save compile time by testing your help file at runtime before compiling. ¢ Support for 
Visual Basic, C, and Pascal Include files. ¢ Generate Microsoft’s Multimedia Viewer files 
from the same project. 


$1 


oO 


9 + shipping and handling 
WinWare Inc. 

P. O. Box 2923 Mission Viejo CA 92690 
Orders: (800) 507-HELP ext. 6003 
TELE:(714) 586-4492 FAX:(714) 586-9792 
BBS:(714) 363-9802 


AS/400 Data Access 


You can finally gain real-time access to the 
AS/400 database and programs from VB, 
Powerbuilder, and Delphi. Our tools make 
the task of creating AS/400 client/server 
applications much easier. Call for info or 
visit us on the Internet: 
http://ourworld.compuserve.com/ 
homepages/rjssoft. 


CyberTools™ 
Text Retrieval 


SQ CyberExplorer eatxt 
| Libraries | Add Documents | Find Files |Advanced | 
Search Expression: 


"Information Discovery Tools" 


Number of retrieved files; 3 File Keywords: 
| [4 f\cyberiad\ann_id.doc discovery ja 
| 12 c:\coolstff\pricingxls done 

} g\ information 
time be 


RJS Software Systems 
P.O. Box 19408 Minneapolis, MN 55419 
TELE:(612) 822-0412 FAX:(612) 822-1364 
CIS: 72700,1207 


Cyberiad Software’s CyberTools are the 
most powerful tools available for text 
retrieval and information discovery. Create 
multiple indexes, insert almost any file 
type or whole directories, and retrieve 
documents with natural queries. Search 
with logical operators, phrases and 
stemmed, sounds-like or fuzzy matches. 
Includes DLL, OCX, sample code and 
applications to help you quickly build 
powerful information discovery solutions. 


$495. 


VB Consultants Needed 


Spectrum Concepts, an information 
technology consulting firm providing 


leading-edge consulting expertise since 
1979, is looking for Visual Basic develop- 
ers to work ON-SITE at our clients in the 
NYC area. We have several immediate 
long-term consulting needs. Please contact 
Michael Cohen at x248. CIS:73304,3026 


Cyberiad Software 
69 Governor Street, Suite 160 
Providence, RI 02906 
TELE: (508) 883-2757 (800) 941-2169 
http://www.cyberiadsoft.com 


Spectrum Concepts Consulting, Corp. 
150 Broadway, Suite 600, Dept. VB 
New York, NY 10038-4493 
TELE:(212) 791-4800 FAX:(212) 791-6639 


Take Charge ! 


PC-Charge makes it easy to process 
credit cards, ATM/Debit cards and check 
guarantee services in Windows. Sales, 
Credits, Voids, everything you need to 
replace that little black box. PC-Charge is 
certified with most major credit card 
processing companies and works with all 
major credit cards. 


A VBX makes it easy to integrate PC- 
Charge into your application. 
Starts at $295. 


Go Software, Inc. 

31 Sherborne Rd., Savannah, GA 31419 
TELE:(800) 725-9264 (912) 925-4048 
FAX:(912) 927-0214 
http://www.netpath.com/-gosoft/ 


Text Control 


5 Te 
‘editor control V2.0 


Fully functional control with on-line documentation that you _ 
can use in your application is available at ) 


~http:/Aww.vbxtras.comvitpfpubMVendors/EariyMoming/Demos/' 
= DOS, Unix, and Rich(RTF) text i i el 
QlLoads and saves. files 


The Early Morning Editor Control V2.0 
is a control for displaying and editing 
text. Supports DOS, Unix, and 
Rich(RTF) text. Now with character 
formatting, split-screen editing, 
bookmarks, and support for custom 
backgrounds and printing. Multi-level 
Undo/Redo. Built-in Search/Replace. 
Comes with VBX and OCX versions. 
Get fully functional demo and online 
docs that you can use in your app, 
refer to screen shot above. $104. 


early morning software 
ORDERS(PsL): 1-800-242-4775 
(VBxtras): 1-800-788-4794 
OTHER: 312-925-1628 
74454.1002@compuserve.com 
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Barco 


des 


Add barcodes to your Windows apps just 
by selecting a truetype font. Interleaved 
2/5, Code 128, Code 3/9, POSTNET, 
UPC/EAN/JAN and Codebar are sup- 
ported. Includes DLL Library to automate 
implementation and optimize output. 
Royalty free—$449. And add a barcode 
scanner to your app with ease. Scanned 
area entered as keyboard entry into any 
input field. Laserguns start at $595, 
Wands at $395, and Portables at $795. 


M.4 is an expert system tool designed for 
embedded use. M.4 offers an easy-to-use- 
and-learn expert system language that 
supports rule-based, procedural and object 
oriented programming. Expertise can easily 
be made available to your Visual Basic 
application using the M.4 Custom Control. 
Complete M.4 package includes develop- 
ment and delivery interfaces for Visual Basic, 
Visual C++, and Toolbook, and embeddable 
libraries for DOS and Windows—Price US 
$995. M.4 Visual Basic Custom Control 
package only, Price US $199. 


HALLoGRAM Publishing 


14221 E. 4th Avenue, Suite 220 
Aurora CO 80011 
TELE:(303) 340-3404 FAX:(303) 340-4404 
http://www.usa.net/hall/ 


Teknowledge Corporation 

1810 Embarcadero Road 

Palo Alto, CA 94303-3308 
(800)285-0500 FAX:(415) 493-2645 


The Ultimate 
Multimedia 
Playground! 


FXToolsVB Professional 

New!! Version 3.0 

Make your VB apps sizzle with special 

effects, sound, and video. FXTools/VB 

Pro provides 9 of the HOTTEST 

multimedia custom controls available! 

e Over 100 professional effects for images, text, shapes, and video including wipes, blinds, 
diagonals, rolls, multiple pass dissolves, and many more. Supports 9 image file formats 
including: BMP, GIF, PCX, TGA, TIF, FIF and JPEG. 

e Display text with 3D fonts, drop shadows, outlines, rotations, 3D borders. 

e Video with effects, 3D borders, volume control and simple command interface. 

e Complete WAV and MIDI sound support including volume and mixer control. 

e Odd shaped hotspots, gradient fill styles, image composition. 

An ideal platform for multimedia development, CD-ROMs, CBT, interactive kiosks, 

presentations, and demos. Professional Edition $349. Standard Edition $199. Free demo 

available. Compuserve: GO IMAGEFX; Internet: http://www.imagefx.com/imagefx 


_— ImageFX 
3021 Brighton-Henrietta TL Road 


—— imageFX Rochester, NY 14623 USA 


TELE:716-272-8030 FAX:716-272-1873 
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ACQUIRE Intelligence! 


ACQUIRE®’s knowledge acquisition system 
and expert system shell provide a step-by- 
step methodology for building knowledge- 
based applications. ACQUIRE®’s Software 
Development Kit lets you embed expert 
systems into your applications. It has custom 
controls for Visual Basic, libraries for DOS, 
and DLLs for ToolBook and Windows. 
Introductory offer for VB readers! 


Acquired Intelligence Inc. 
TELE:(604) 479-8646 FAX:(604) 479-0764 
email:sales@aiinc.bc.ca 


Online User Registration 


Dramatically increase your customer 
registration rates with this complete, 
proven electronic registration system. 
Client, Host, and Test applications 
provided. No programming required. Fully 
configurable. Integrates with your 
application or install program. All you 
need is Windows 3.1 or later and a modem. 
Electronic registration handling services 
via our equipment also available. $495. 


Vertical Technology Solutions 
TELE:(206) 488-3195 FAX:(206) 481-1196 


Reprints 


Leverage the power of the leading 
Windows development magazine to 
promote your company and its products. 
Use VBP] reprints for: 


¢ Sales Collateral 
¢ Seminars and Workshops 
¢ Trade Shows 

e Marketing/Public Relations 


You can have articles, columns or 
advertisements professionally reprinted 
in four color or black and white as it 
appears in the magazine or with a 
customized layout. 


Call Andrew King at (415) 833-7117 
for more information. 


Innovative Solutions & Technologies, Inc. 


Innovative Solutions & Technologies, Inc. 


OpenExchange 
Import/Export! 


©) file Edit Insert Window Help = a 


Reedy 


OpenExchange VBX/Developer’s Kit adds 
complete user-friendly data import/export 
capabilities to your Windows application in 
minutes w/o programming! Features include 
a full ready-made user-interface w/drag & 
drop field mapping, calculated fields, saves 
configurations for re-use, & more. Easily 
import/export dBase, Access, FoxPro, 
Paradox, Btrieve, Excel, Lotus, ASCH, & more! 
The VBX interface gives you integral control 
over the EXE component. Why spend weeks 
or months re-inventing the wheel? 

Free OCX Upgrade! Other solutions 
available! Call TOLL FREE for FREE DEMO 
& info. 60-Day MBG 


904 Jefferson Ave Joplin, MO 64801 


TELE:(800) 962-4855 FAX:(417) 781-3299 


FAST Spreadsheet Access! 


OpenExchange DLL allows you to quickly & 
easily read & write files in all versions of 
Excel, Lotus 123, Quattro Pro, Symphony, & 
even dBase & Paradox! Fast & compact 
(145K) provides a standard API for all for- 
mats. Avoids the overhead of OLE & DDE! 
Works in all DLL languages including VB, 
Delphi and C. Royalty-free distribution. Only 
$295+$8 s/h. 60 Day MBG. Call Us! 


904 Jefferson Ave. Joplin MO 64801 


TELE:(800) 962-4855 FAX:(417) 781-3299 


NT/95 Port I/O 


The WinStar Hardware Classes library 
provides port I/O, physical memory 
mapping and interrupt handlers for 32- 
bit VB4 and C/C++ applications. 

NT and Win95 device drivers, utilities, 
online help and examples. $399. 


WinStar Technologies 
82 Gates St. 
San Francisco, CA 94110 


TELE:(415) 647-2815 FAX:(415) 647-9573 


E-MAIL: 74367.1773@compuserve.com 


NetWare Interface for VB 


Save hours of development time writing 
NetWare-Aware Windows 95, 3.1 and NT 
client applications using The NetWare 
Interface for Visual Basic SDK. This 
developer kit contains all of the latest 
DLL's, function declares, structure/constant 
definitions, sample code, and the “VB 
Programmer’s Guide to NetWare”. Supports 
NetWare 3x, 4x (NDS). 


Ztech Software - Austin, Texas 
TELE:(512) 495-9101 
FAX:(512) 495-1803 


VB Notebook 


The perfect tool to keep notes of every- 
thing in your Visual Basic program. No 
more clicking and searching to find what 
you need. A clean way of keeping track of 
your project, and reduce development 
time. $23+$3.50 s&h. 


4Sight Software 
18 Como Drive 
Somerset, NJ 08873 
TELE:(908) 214-2745 


Total Access 


Automate the maintenance of Microsoft 
Access/ Jet Engine (*.MDB) databases. 
Repair, compact, and back up (copy or 
zip) multiple databases. Even backup data 
while users are in the database! 

Databases can be processed hourly, daily, 
weekly, or monthly. A complete audit trail 
of actions, times, and errors is maintained. 
Error messages can even be sent to an 
administrator via E-MAIL. OLE Server 
included. 30 day MBG. $199+$5 S&H. 


FMS, Inc. 
8027 Leesburg Pike, Suite 410, 
Vienna, VA 22182 
TELE:(703) 356-4700 FAX:(703) 448-3861 
CompuServe: 73710,463 
Internet: http://www.fmsinc.com 


Custom Controls for Windows Sockets 
HTTP, HTML, FTP, Telnet, SMTP, POP3, 
DNS, Ping, Image Viewer and R-LIB 
eVBX, 16-bit and 32-bit OCX components 
eEvery major Internet protocol included 

e Ability to create client and server apps 
eRenders BMP/PCX/GIF/JPEG/XBM 
eHTML renders docs to 2.0, some 3.0 specs 
eFull featured sample applications 

e Works with Visual Basic 3.0/4.0 and ALL 
WINSOCK compliant TCP/IP products 
All this and NO ROYALTIES 

Only $247 for a limited time (save $100) 
Sold with unconditional 90 day mbg. 

See our Web site for more details. 
http://www.earthlink.net/~catalyst/ 


SocketTools from Catalyst Software 
56925 Yucca Trail Ste. 254 
Yucca Valley, CA 92284 
TELE: (800)776-3818 or (619)228-9653 
FAX: (619)369-1185 sales@catalyst.com 


CodeOnly Controls 
Add Scheduling, Calendar, Clock and 
Slider Controls to Visual Basic programs 
without using VBX, OCX or DLL's. 

All controls are produced directly from 
VB code modules. Fully customize the 
3D, beveling, fonts and colors for each 
control. Go VBPJ search: Wolfebyte 


Subscribe Now! 


Visual Basic Programmer’s Journal is the 
most comprehensive source of information 
on Visual Basic. No other magazine 

covers VB in as much depth or provides 
as much useful information on Windows 
development. Your subscription will 
include twelve monthly issues for only 
$27.95—that’s a savings of 41% off 
the annual newsstand cover price! 
To subscribe now call 800-848-5523. 


WolfeByte Ltd. 
4925 Beverly Blvd, Suite 11 
Los Angeles, CA 90004 
TELE: (800)-467-4787 


VBXpert 


VBXpert embeds rule-based knowledge 
within Visual Basic applications by encap- 
sulating a state of the art inference engine 
(based on Eclipse). Provided is an inference 
engine custom control and a Visual Basic 
API to its embedable DLLs. The first month 
is FREE! 


For customer service inquiries on your 
current subscription please call 
303-684-0365 or send a fax to 
303-661-1816. 


FAWCETTE 
TECHNICAL 
PUBLICATIONS 


Fawcette Technical Publications 
209 Hamilton Ave. 
Palo Alto, Ca 94301-2500 


The Haley Enterprise, Inc. 
413 Orchard Street 
Sewickley, PA 15143 
TELE:(800) 233-2622 FAX:(412) 741-6457 

E-Mail:info@Haley.COM 


You work too hard to lose sales to piracy! 


Seu nel 


Software Protection 


Don’t let pirates steal your sales and revenue. 


Sentinel” - the world’s leading software protection 
Software piracy is at an all-time high, costing developers 
like you billions in lost sales each year. That’s why 
more developers protect software and ensure revenue 
with Sentinel. 


Discover the Sentinel advantage - easy to implement, 
transparent to customers, and the most advanced 
protection. Only Sentinel gives you leading-edge technology, 
ISO 9002 certified quality and over 99°°% reliability. 


Protect your software investment - call for a FREE 
Sentinel Guide to Software Protection. Or start protection 
immediately, order a Sentinel Developer’s Kit. Each kit has 
a Sentinel key and the Sentinel CD-ROM - it’s everything 
you need to sell more software and make more money. 


Rainbow Technologies, Inc. 
50 Technology Drive 
Irvine, CA 92718 
(800) 852-8569 TELE:(714) 450-7300 FAX:(714) 450-7450 
Internet: info@rnbo.com WWW: http://www.rnbo.com 


<4 


CONNECTION 


Eee eee 
CONNECTION 


Your Section for the OLE Connection 


This special advertising section highlights tools designed 
specifically for Windows programmers. If you are interested 
in placing an ad in this section, please call Robin Nakamura 
at 415-833-7100. 


This disclaimer covers all trademark references in this 
section. Advertisers recognize the trademark rights of 
other vendors. Specifically, Visual Basic, Microsoft, MS-DOS, 
Win32, Win32s, Microsoft Access, and Windows are registered 
trademarks and Visual C++ and Windows NT are trademarks 
of Microsoft Corporation 


Custom Screens 
at Run-Time 
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e Change captions ¢ Resize or Move controls 
e Change colors and fonts © Disable/Enable 
controls ¢ Make controls Visible/Invisible. 
..at Run-Time! 

User Options OCX allows your users to modify 
the look of your applications at run-time. Just 
place the control in your form, and write one line 
of code, “UserOptions.Modify.” Your users can 
modify your screen, and save, without changing 
your source code. Only $99 +s &h. 


ABRISOFT: 


ABRISOFT, Inc. 
4851 NW 103rd Avenue, #55C 

Sunrise, FL 33351 

PH: (954) 471-8818 © FAX: (954) 741-0197 
http://www.abrisoft.com 
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Graph, Scientific Graph, and Pie Chart controls 
for the ultimate in charting. No overlapping 
text, no flashing redraws, built-in table, multi 
left/right Y axes, extensive annotations, data- 
cursors, user Customizable, zooming, drill-down, 
real-time, and much more. Free demo or down- 
load “pedemo.zip” from CIS’s VBPJFO. $349 


GigaSoft, Inc. 
696 Lantana’ Keller, TX 76248 
(817) 431-8470 
Fax: (817) 431-9860 


Annotation, Drawing, 
and Hyperlinking 
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The AccuSoft Redlining T Toolkit (ART) is a very 
powerful and flexible API toolkit that can be 
used to add annotation, drawing, hyperlinking, 
and more to any application in minutes. ART 
works as an overlay to any type of document: 
text, graphics, images, empty windows and more. 

ART objects include vector graphics, text, 
bitmaps, sound, and user-defined objects, which 
can be anything you desire. Any object can be 
used to create a link to any type of data or action. 


AccuSoft 


High Performance Imaging” 


AccuSoft Corporation 
Two Westborough Business Park 
Westborough, MA 0158] 
(800) 525-3577 © PH: (508) 898-2770 © FAX: (508) 898-9662 
hitp://www.accusoft.com © Compuserve: Go AccuSoft 


Powerful Geographic Mapping and Analysis (GIS) 
OLE Control. Links any ODBC database to map 
entities. Entity selection, SQL and Geo-query- 
ing, visual data analysis, address matching, 
measuring, and display tools. Includes a CD- 
ROM with royalty free mapping data and trans- 
lators for other map formats. Coordinate sys- 
tem translator DLL included for GPS and other 
applications. Ideal for client-server or stand- 
alone applications. No royalties. $495.00 + s&h. 
30 day money back guarantee. 
Sylvan Ascent Inc. 
P.0. Box 4792 © Santa Fe, NM 87502 


Tel:800-362-8971 Fax: 505-986-0906 
Internet: www.sylvanmaps.com/ocx Compuserve: GO SYLVANASCENT 


Media Architects, Inc. 

7320 SW Hunziker Rd., # 305 © Portland, Oregon 97223 
(503) 639-2505 

Fax: (503) 620-5451 

BBS: (503) 598-1165 

74774,707 or GO MEDARCH 

Internet: www.mediarch.com 


SylvanMaps/OCXx™ 


Add Multimedia Impact to Windows 95 


32-bit OLE Controls deliver dramatic performance and ease of use 


Industrial PLC OCX/ 
VBX for MMI 


eS TSR ELST) 


AB, Modicon/Square D, GEFanuc, TI/Siemens, Bristol, 
IDEC, Ethernet 
¢ Context-sensitive help/manual built-in 
¢ Complete protocol support in all OCX/VBXs 
¢ Comm Protocol conversion or arbitration 
¢ VB based MMI Dev Kit available 
Wealso do custom PLC logic/MMI/OCX/VBX/Windows 
products or replace III party MMI packages with VB. 
Build MIS, Expert Systems/Artificial Intelligence, into 
live MMI with CAD, manuals, spec sheets etc. for 
1SO9000. Ask for our OCX/VBX package deal. 

Parijat Controlware, Inc. CIS:(102015,2321] 

3558 Ashfield Dr. #A Houston TX 77082. USA. 


Tel(713)556-6900. Fax(713)589-7707 
In Europe: Tel +41 53-22 5572 Fax+41 53-22 4420 


MediaKnife/OCX™ lets you quickly create Windows 95 appli- 
cations integrating special effects, animation, sound etc... 
while still developing in Visual Basic®. Just drag the controls 
onto aform and set the property pages to get started. Utilize 
transition effects, background buffering, irregular hotspots 
and custom cursors. Sprites with collision detection, and 
drag and drop capabilities. Includes editors for hotspot 
layout, sprite assembly, and batch palette editing. Also 
available as 16-bit VBX. 

VideoPlay/OCX™ makes it a snap to integrate AVI, 
Quicktime and MPEG video playback. Drag on and size the 
video area then use properties to play the video, adjust 
speed, frame sequence, even set events for end of video, on 
specific frame numbers or at regular time intervals. 

Available soon: ImageKnife/OCX™ lets you acquire 
images up to 24-bit color via TWAIN scanners, display 
with pan, zoom and automatic scrollbars, print to Win- 
dows printers, process images in memory and write to 
files or databases. 

Royalty-free distribution and a 90-day money back guar- 
antee! MediaKnife/OCX $399, VBX $349, OCX & VBX: $599 , 
VideoPlay/OCX $79, ImageKnife/OCX $499, VBX Pro Pack 
$349, OCX & VBX: $699 
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GETTING STARTED 
WITH VBA 


Add a Toolbar to 
Your App 


Use VB4’s new ToolBar control to 
give the user easy access to the 
features of your application. 


by Chris Barlow 


ou probably haven’t seen a recent professional Win- 
dows application without a toolbar. Toolbars give users 
quick access to your application features without forc- 
ing them to navigate menus. If you want your Visual Basic 
application to look and feel like these professional applications, 
you need to use this control. Fortunately, the new ToolBar 
control included with Visual Basic 4.0 is easy to use. 

First let’s get to a common starting point. You can follow the 
code examples in this column to add a toolbar to any of your 
existing applications. I'll build upon the text editor example 
from last month’s column. If you want to use the same code and 
you haven’t downloaded the source code for the text editor 
from VBPJ’s online sites, just draw a RichTextBox and 
CommonDialog control on an empty form and create a standard 
File menu with New, Save, and Exit menu items. For more 
information on the new RichTextBox and CommonDialog con- 
trols in Visual Basic 4.0, refer to my last column. 

Creating menus can be time consuming because you have to 
type all the menu properties for each form. How about a short- 
cut? If you have another form with a standard Windows menu, 
open it with Notepad and look at the source code for the form. 
You'll see a set of code starting with “Begin VB.Menu...”(see 
Listing 1). Copy this code to the clipboard, then open your new 
FRM file with Notepad and paste in this code. I’ve saved this 
code in a text file so I can paste it into my FRM file when I need 
a standard menu. It saves a lot of typing! Be sure to save the file 
as ASCII text so Visual Basic can load it. 


MORE COMPLICATED, BUT WORTH IT 

This control is a bit more complicated than the RichTextBox and 
CommonDialog controls you’ve learned about so far. Visual 
Basic 4.0 is designed to use OLE Automation throughout, so you 
should become familiar with using these Visual Basic objects 
with their own properties, methods, and collections. One of the 
reasons the ToolBar control is more complicated than the other 


Chris Barlow is president and CEO of SunOpTech, a developer of 
manufacturing decision-support applications including the 
ObjectBank and the ObjectJob Systems, where he and Ken 
Henderson hold a software patent related to decentralized distrib- 


uted asynchronous object-oriented systems. Chris holds degrees» 


from Harvard Business School and Dartmouth College where he 
worked with Drs. Kemeny and Kurtz on the BASIC language. Reach 
Chris on the Internet at ChrisB@SunOpTech.com or through 
SunOpTech’s World Wide Web server at www.SunOpTech.com. 


controls is that the toolbar buttons are a collection of Button 
objects with their own properties and methods. And to make it 
a bit more complex, the images on the button faces are con- 
tained with the ListImages collection of an ImageList control 
(see Figure 1). 

To add a toolbar to your application, you need to perform 
several steps. I always recommend you start writing a proce- 
dure by listing the steps in pseudocode: 


1. Add an ImageList control to your form. 

2. Insert pictures for the button faces to the ListImages 
collection of the ImageList control. 

3. Add a ToolBar control to your form. 

4. Set the ToolBar ImageList property to bind the toolbar 
to your ImageList control. 

5. Add Button objects to the toolbar. 

6. Set each button’s properties to bind the button image 
to the proper image. 

7. Write code to handle toolbar button clicks. 


lll go through each of these steps in detail. Start by drawing an 
ImageList control on your form, right-click on the control to 
display the Properties dialog, go to the Images tab and click on the 
Insert Picture button. If you look in the bitmaps/tlbr_w95 folder 
you'll find a good selection of bitmaps for the toolbar buttons. 
Insert pictures for New, Open, Save, Print, Find, Left, Center, and 
Right. Now go to the Colors tab and change the BackColor 


us i 
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Begin VB.Menu mnuFile 
Caption = "&File" 
Begin VB.Menu mnuNew | 
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LISTING 1 How About a Shortcut? Creating menus can be time 

consuming because you have to type all the menu properties 

for each form. If you have another form with a standard Windows 

menu, open it with Notepad and copy the source code to the clipboard. 

Then open your new FRM file with Notepad and paste in this code. Be 
sure to save the file as ASCII text so Visual Basic can load it. 
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property to the system color “Menu Bar” and the MaskColor 
property to the system color “Button Face.” If you don’t adjust the 
colors, you'll find that the images are dithered when they appear 
on the toolbar buttons and they'll be difficult to see on the button 
faces. At run time you can use the Add method of the ListImages 
collection to add other images to the ImageList control. 

Now that you havea collection of images for your toolbar, add 
the ToolBar control to your form and right-click on the control to 
display its property dialog. On the General tab change the ImageList 
property to bind the toolbar to your ImageList control. Be sure 
you have added all theimages that you will need to your ImageList 
control before you bind it tothe toolbar because you cannot make 
changes to a bound ImageList control. 

Each toolbar has a collection of Button objects. You can add 
Button objects to the toolbar at run time with the Add method of the 
Buttons collection. At design time, on the Buttons tab of the ToolBar 
control’s property dialog, click on Insert Button to add a button. 
Button objects can contain either an image or a caption, or both. 
Because each Button object has a ToolTipText property, however, 
you probably won't need to design a toolbar with both images and 
captions. You'll want to set the Key property of each Button object 
so you can identify which button the user has clicked on. 

Insert five buttons on your toolbar, set their Key and 
ToolTipText properties to “New,” “Open,” “Save,” “Print,” and 
“Find,” and bind them to images one through five of the ImageList 
control. Click on the Apply button to see your new toolbar. 

You can design a better toolbar by using the Style property 
of the Button object. The default style is a normal button, just 
like the buttons now on your toolbar. To separate the Print 


Option Explicit 
Public sFind As String 


Private Sub Combol_Change() 
RichTextBoxl.SelFontSize = Combol 
RichTextBoxl.SetFocus 

End Sub 


Private Sub Combol_Click() 
RichTextBoxl.SelFontSize = Combol 
RichTextBox1.SetFocus 

End Sub 


Private Sub Form_Load() 

"Initialize the combo box 

Show 

With Combol 

.Width = Toolbarl.Buttons("combo1").Width 
wLeft = Toolbarl.Buttons("combol").Left 
.Top = Toolbar1.Buttons("combol").Top 
AddItem "10" 

.AddItem "12" 

-AddItem "14" 

.AddItem "16" 

.ListIndex = 0 

.ZOrder 

End With 

End Sub 


Private Sub Form_Resize() 

With Combol 

.Width = Toolbar1.Buttons("combol").Width 
.Left = Toolbar1.Buttons("combol").Left 
.Top = Toolbarl.Buttons("combol").Top 

End With 


= 


ToolBar Control 


Objects and Collections. You'll need to know how 

these objects relate to each other to develop a working 
toolbar. The toolbar buttons are a collection of Button objects with 
their own properties and methods. And to make it a bit more 
complex, the images on the button faces are contained with the 
Listlmages collection of an ImageList control. 


button slightly from the New, Open, and Save buttons, insert 
another button with a style property of “separator.” 

Onthe Buttons tab, move backtothe Save button by changing the 
index to three and click on the Insert Button button. Then change the 
Style property to “separator.” Insert another separator button be- 
tween the Print and Find buttons and after the Find button. 

Buttons can also be part ofa button group where only one button 
at atime can be pressed. For example, if the text in our RichTextBox 


End Sub 


Private Sub mnuExit_Click() 
Unload Me 

End 

End Sub 


Private Sub mnuFind_Click() 

sFind = InputBox("Find what?", , sFind) 
RichTextBox1.Find sFind 

End Sub 


Private Sub mnuFont_Click() 
CommonDialogl.Flags = cd1CFBoth + cd1CFEffects 
CommonDialog1.ShowFont 
With RichTextBoxl 
.SelFontName = CommonDialogl.FontName 
.SelFontSize = CommonDialogl.FontSize 
-SelBold = CommonDialog1.FontBold 
.SelItalic = CommonDialogl.FontItalic 
.SelStrikethru = CommonDialogl.FontStrikethru 
.SelUnderline = CommonDialog1.FontUnderline 
End With 
End Sub 


Private Sub mnuNew_Click() 
RichTextBoxl.Text = "" 
End Sub 


Private Sub mnuNext_Click() 

RichTextBoxl.SelStart = RichTextBoxl.SelStart + _ 
RichTextBox1.SelLength + 1 

RichTextBoxl.Find sFind, , Len(RichTextBox1) 

End Sub 


Private Sub mnuOpen_Click() 
CommonDialog1.Show0Open 


CONTINUED ON NEXT ree. | 


LISTING 2 Complete Toolbar Code. Use this code to add a toolbar to your application. The project files, contained in a file called TOOLBAR. ZIP, 
are also available on the VBCD, in the Magazine Library (#3) of the VBPJ Forum on CompuServe (GO WINDX with WinCIM), the 
VBPJ Development Exchange World Wide Web site (http://www. windx.com), or the VBPJ site on The Microsoft Network (GO WINDX). 
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CONTINUED FROM PREVIOUS PAGE. 
RichTextBoxl.LoadFile (CommonDialogl.filename) 
End Sub 


Private Sub mnuPrint_Click() 
CommonDialogl.Flags = cd1PDReturnDC + cd1PDNoPageNums 
If RichTextBoxl.SelLength = 0 Then 
CommonDialogl.Flags = CommonDialogl.Flags + _ 
cd1PDA11Pages 
Else 
CommonDialogl.Flags = CommonDialogl.Flags + _ 
cd1PDSelection 
End If 
CommonDialog1.ShowPrinter 
RichTextBox1.SelPrint CommonDialog1.hDC 
End Sub 


Private Sub mnuSave_Click() 
CommonDialog1.ShowSave 

RichTextBoxl.SaveFile (CommonDialogl.filename) 
End Sub 


Private Sub RichTextBox1_SelChange() 
Select Case RichTextBox1.SelAlignment 
Case rtfLleft 
Toolbar1l.Buttons("Left").Value = tbrPressed 
Case rtfCenter 
Toolbar1l.Buttons("Center").Value = tbrPressed 
Case rtfRight 
Toolbarl.Buttons("Right").Value = tbrPressed 
Case Else 
Toolbar1.Buttons("Left").Value = tbrUnpressed 
Toolbarl.Buttons("Center").Value = tbrUnpressed 
Toolbarl.Buttons("Right").Value = tbrUnpressed 
End Select 
Combol.Text = RichTextBox1.SelFontSize 
End Sub 


Private Sub Toolbarl_ButtonClick(ByVal Button As 
Button) 
Select Case Button.Key 


Case "New": mnuNew_Click 
Case "Open": mnuOpen_Click 
Case "Save": mnuSave_Click 
Case "Print": mnuPrint_Click 
Case "Find": mnuFind_Click 
Case "Left": RichTextBoxl.SelAlignment = rtfLeft 
Case "Center": RichTextBoxl.SelAlignment = rtfCenter 
Case "Right": RichTextBoxl.SelAlignment = rtfRight 
End Select 
|__End Sub | 


control can be only left-aligned, centered, or right-aligned, then only 
one of the Left, Center, or Right buttons should be pressed. A button 
group is defined as a group of buttons with a “button group” style 
surrounded by buttons with a “separator” style. 

Add three more buttons with Key and ToolTipText proper- 
ties of “Left,” “Center,” and “Right” to your toolbar and set their 
style to “button group.” 

Buttons can also have a style property of “placeholder” that 
allows you to add other controls to the toolbar. Add a combo 
box that will allow the user to set the size of the font. Add two 
more buttons to your toolbar—one with a “separator” style and 
the other with a “placeholder” style. Set the Key property of the 
last button to “combol,” and the width property to 1000. Then 
draw a ComboBox control on the toolbar. 

You'll need to add one more invisible button to your toolbar 
with a style of “default.” A bug in Visual Basic prevents the 
toolbar from wrapping properly if the last button on the toolbar 
has a placeholder style. Now that your toolbar design is com- 
plete (see Figure 2), it is time to add the code. 


THE CODE BEHIND THE BAR 


Because you have a combo box on your toolbar, you'll need to 
add code to initialize the combo box and to make sure it is 


STARTED 
WITH VBA 


ars 
FIGURE 2 Your New Toolbar. The toolbar you've created features 
a combo box control for font selection, in addition to 

buttons for New, Open, Save, Print, Find, and text alignment. 


located on the placeholder button of the toolbar. In the 
Form_Load event, add this code: 


Private Sub Form_Load() 

"Initialize the combo box 

Show 

With Combol 

«Width = Toolbarl.Buttons("combol").Width 
-Left = Toolbarl.Buttons("combol").Left 
-Top = Toolbar1.Buttons("combol").Top 
-AddItem "10" 

.AddItem "12" 

-AddItem "14" 

-AddItem "16" 

-ListIndex = 0 

.ZOrder 

End With 

End Sub 


You need to copy this “tracking” code to the Form_Resize 
event so the combo box always stays in the proper place: 


Private Sub Form_Resize() 

With Combol 

«Width = Toolbarl.Buttons("combol") .Width 
-Left = Toolbarl.Buttons("combol").Left 
-Top = Toolbar1.Buttons("combol").Top 

End With 

End Sub 


Handling the toolbar clicks will be fairly easy because you 
already have menu items for most of these functions. The toolbar 
ButtonClick event passes the button object that the user clicked 
on so you can write a Select statement based on the Key property 
of the button: 


Private Sub Toolbarl_ButtonClick(ByVal _ 
Button As Button) 

Select Case Button.Key 

Case "New": mnuNew_Click 

Case "Open": mnuOpen_Click 

Case "Save": mnuSave_Click 

Case "Print": mnuPrint_Click 

Case "Find": mnuFind_Click 

Case "Left": _ 
RichTextBox1.SelAlignment = rtfLeft 

Case "Center": _ 
RichTextBox1.SelAlignment = rtfCenter 

Case "Right": _ 
RichTextBoxl.SelAlignment = rtfRight 

End Select 

End Sub 
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The only new code—the Case “Left,” 
Case “Center,” and Case “Right” state- 
ments—sets the alignment property of 
the RichTextBox control based on which 
button the user clicked on. This will 
change the alignment ofthe selected para- 
graphs or, if no text is selected, the cur- 
rent paragraph. You can set these align- 
ment buttons to display the actual align- 
ment of the text as you move through the 
text by setting each button’s Value prop- 
erty within the SelChange event of the 
RichTextBox control. Notice how the 
“Case Else” statement “unpresses” all 
buttons in the group if the alignment is 
other than left, centered, or right: 


Private Sub RichTextBox1_SelChange() 

Select Case RichTextBox1.SelAlignment 

Case rtfLleft 
Toolbar1.Buttons("Left").Value = _ 

tbrPressed 

Case rtfCenter 
Toolbarl.Buttons("Center").Value = _ 

tbrPressed 

Case rtfRight 
Toolbarl.Buttons("Right").Value = _ 

tbrPressed 

Case Else 
Toolbarl.Buttons("Left").Value = _ 

tbrUnpressed 
Toolbarl.Buttons("Center").Value = _ 

tbrUnpressed 
Toolbarl.Buttons("Right").Value = _ 
tbrUnpressed 

End Select 

Combol.Text = RichTextBoxl.SelFontSize 

End Sub 


The last line of code in the 
RichTextBox1_SelChange() procedureuses 
the SelFontSize property to display the font 
size as the cursor moves through the text. 
Now you add code to change the font size of 
the selected text when the user makes a 
selection from the combo box on your 
toolbar. This is easy—just set the SelFontSize 
property of the RichTextBox control to the 
default value of the combo box and return 
the focus to the RichTextBox control: 


Private Sub Combol_Click() 
RichTextBoxl.SelFontSize = Combol 
RichTextBoxl.SetFocus 

End Sub 


Now youhavea fully functional toolbar 
for your application (see Listing 2). One of 
the cool things you get for “free” with the 
ToolBar control is the ability to allow the 
user to customize the toolbar by reorder- 
ing and removing buttons. If you set the 
Customize property of the toolbar to True, 
the user can double-click on the toolbar 
at run time to bring up a customize dialog 
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by which he or she can modify the toolbar 
you set up at design time. You can even 
use the SaveToolBar method to store the 
current toolbar settings in the Registry 
and use the RestoreToolBar method to 
reload it the next time the user runs your 
application. 

The code discussed in this column, 


contained in a file called TOOLBAR.ZIP, 
is also available on the VBCD, in the 
Magazine Library (#3) of the VBPJ/Forum 
on CompuServe (GO WINDX with 
WinCIM), the VBPJ Development Ex- 
change World Wide Web site (http:// 
www.windx.com), or the VBPJ site on 
The Microsoft Network (GO WINDX). %! 
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Join the Windows Components Forum, sponsored by Fawcette Technical 
Publications and CompuServe. Here you will find your most comprehensive 
resource for the Windows programmer—complete with top notch technical 
support from all the major custom control vendors plus an entire forum 
dedicated to Visual Basic Programmer’s Journal, the leading Windows 
development magazine. You can download the latest code, talk to the 
editors, chat with the experts and much more! 


Get support from the top Custom Control vendors including: 

¢ Sheridan * MicroHelp Crescent * Desaware * ImageFX ¢ Stylus Innovation 
* VideoSoft * Visual Components ° Sax Software * Aardvark ¢ Media 
Architects * A&G Graphics ¢ Crystal * Avanti * Apex * London Software * 
Success Ware ¢ Mabrye ViewPoint Technologies ¢ Software FX * Pronexus 


Join today! If you aren’t already a member, join now and become part 
of the core community of Windows development professionals. 


Call CompuServe today at 800-524-3388. Ask for Operator 643. 


Fawcette Technical Publications 

209 Hamilton Avenue ° Palo Alto, CA 94301-2500 
Phone: (415) 833-7100 ¢ Fax: (415) 853-0230 
CIS: 74601,2631 
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Making Progress 


Build your own Progress Bar class 
to use in both 16- and 32-bit 
versions of VB4. 


by Karl E. Peterson 


indows 95 and Windows NT offer many new standard 
4] controls for Visual Basic programmers. Unfortunately, 
you cannot use these controls in the 16-bit version of 
VB4, even when running in 32-bit operating systems. This month 
I will present a VB4 class module that re-creates the new 
ProgressBar control. You can use it in both 16- and 32-bit 
versions of VB4, or modify the same general technique to 
operate in VB3, without regard to which operating system your 
application is running under. 

In the VBPJ January 1996 Programming Techniques column, 
I showed how to add capabilities to an existing control by 
encapsulating “type-amatic” searches for list boxes within a 
class module. In this month’s technique, a class module empow- 
ers one standard control to emulate another. Hopefully, the 
finished class also will prove useful for those of you writing 16- 
bit code, or conditionally compiling to both 16- and 32-bit 
executables. Those of you who’ve already committed com- 
pletely to 32-bit may wonder if there’s any value in re-creating 
the ProgressBar. Consider that it’s one less OCX you'll need to 
distribute if your project doesn’t use any of the other Windows 
95 common controls. 

The general idea behind the CProgressBar class is that a 
picture box on a form will be used as a canvas upon which the 
class can draw a progress indicator. You will need a number of 
private member variables within the class to track its internal 
data. After you insert a new class module in your project, enter 
these declarations in its General section: 


" Set aside storage for private member 
" variables. 

Private m_Bar As PictureBox 

Private m_Val As Long 

Private m_Min As Long 


KarlE. Peterson is a GIS analyst with a regional 
transportation planning agency in Vancouver, 
Wash., and a member of the VBPJ Technical 
Review Board. Karl coauthored Visual Basic 4 
How To, from Waite Group Press. Online, he’s 
the 32-Bit Bucket section leader in the VBPJ 
Forum and a Microsoft MVP in the MSBASIC 
Forum. Contact Karl in either CompuServe 
location at 72302, 3707. 


Private m_Max As Long 

Private m_fColor As Long 
Private m_bColor As Long 
Private m_CellWidth As Integer 
Private m_CellHeight As Integer 
Private m_xMargin As Integer 
Private m_yMargin As Integer 
Private m_Cells As Integer 


Use the class’ Initialize event to set default values into 
several of the member variables. Set the default minimum and 
maximum property values to match those of the real 
ProgressBar control, zero and 100. Likewise, set the initial 
value to zero. Set m_Bar, the canvas upon which drawing will 
take place, to Nothing because you do not know what picture 
box you will use at this point. Set the foreground and back- 
ground colors to match the operating system’s default col- 
ors. Use the x and y margin values to calculate the number 
and size of cells to draw. 


Private Sub Class_Initialize() 
" Set default values for class 
" properties. 
Set m_Bar = Nothing 
mVal = 0 
mMin = 0 
m_Max = 100 
m_fColor = vbHighlight 
m_bColor = vb3DFace 
m_yMargin = 2 
m_xMargin = 3 

End Sub 


The CProgressBar class exposes a Canvas property, which 
you will use to set or retrieve the picture box object used for 
the emulated progress bar (see Listing 1). Download 
PT0396.ZIP for demo projects using the CProgressBar class, 
as well as other code from this column, from the Magazine 
Library of the VBPJ Forum on CompuServe. In the Property 
Set routine, the new value for this property is received As 
Object. This allows the class to detect what type of object the 
routine passed, should an object besides a picture box be 
assigned to the Canvas property. 

Ifa picture box was received, a reference to it is stored in the 
m_Bar member variable, and new ForeColor and BackColor 
values are assigned to it. You also set it to use Pixels as its 
Scaieliode, so that you can perform later drawing operations 
more easily. If the passed object is not a picture box, the routine 
generates a runtime error with appropriate explanation, and the 
client application is left to handle it. 

For consistency, use standard property names for your 
classes, especially when they’re emulating something else. The 
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Min, Max, and Value properties each have their respective Let 
and Get routines (these listings are posted in the VBPJ Forum). 
Property procedures have an advantage over Public variables in 
that you can validate the incoming values. For these properties, 
therules are simple and followthoseused by the real ProgressBar 
control. The Min must be less than the Max, and the Max must 
be greater than the Min. If you do not meet either of these 
conditions, the routine generates a runtime error, with an 
explanation detailing the source of the error and its cause. The 
Value property must fall somewhere between the Min and the 
Max, but is simply set to either extreme should an out-of-range 
value be received. When a client application alters any of these 
three properties, that Let procedure calls the public Refresh 
method. 

The Refresh method repaints the emulated progress bar, and 
may be called directly by the client application. If the optional 
parameter ClearFirst is set to True, the Canvas (m_Bar) will first be 
erased using its Cls method. Then, the private RedrawMe proce- 
dure is called to do the actual drawing of the progress bar cells: 


Public Sub Refresh(Optional ClearFirst) 


' Update display, clearing 


——- 


Public Property Set Canvas(NewObj As Object) 


" Set new PictureBox as Canvas property. 
If TypeOf NewObj Is PictureBox Then 
Set m_Bar = NewObj 
m_Bar.ForeColor = m_fColor 
m_Bar.BackColor = m_bColor 
m_Bar.ScaleMode = vbPixels 
ResizeEx 
Else 
Err. Raise Number:=vbObjectError + 1, _ 
Source:="CProgressBar.Canvas", _ 
Description:="Canvas property must be _ 
of type PictureBox.” 
End If 
End Property 


Public Property Get Canvas() As Object 


" Return PictureBox as Canvas property. 


Set Canvas = m_Bar 


End Property 


Tanta Preparing the Class’ Canvas. The Canvas property 
sets and returns the picture box you will use for your 
custom progress bar. 


___| 


Progress Bar Demo 


Custom Control. This illustration shows how the 
CProgressBar class is actually smarter than the Windows 95 custom 
control. By using the ResizeEx method, the programmer specifies 
that an exact number of whole indicator cells are drawn, rather 
than accepting the default behavior of a partial last cell as 
Windows 95 does. 


FIGURE | CProgressBar “Control” Outsmarts the Win95 


PROGRAMMING 
TECHNIQUES 


' it if requested. 
If Not m_Bar Is Nothing Then 
If Not IsMissing(ClearFirst) Then 
If ClearFirst Then 
m_Bar.Cls 
End If 
End If 
RedrawMe 
End If 
End Sub 


Before any drawing can take place, you need to make a 
number of calculations. You may have noticed that a ResizeEx 
method was called from the Set Canvas procedure. The ResizeEx 
method, being public, is also available to the client application. 
ResizeEx calls the CalcCellSize private method, which provides 
the dimensions for each cell and the number of cells required to 
fill the progress bar (this method is posted in the VBPJ Forum). 
It uses margins defined in the class Initialize event, and a 2:3 
width-to-height ratio to determine individual cell sizes. So far, 
I’ve directly emulated the real ProgressBar control. 

ResizeEx takes things one step further, though. The real 
ProgressBar control behaves in a non-integral manner, often 
using a partial cell to indicate final completion (see Figure 1). 
ResizeEx determines whether this last partial cell is wider or 
narrower than half a whole cell. If wider, ResizeEx resizes the 
Canvas object again, enlarging it to include the entire last cell. If 
narrower, ResizeEx shrinks the Canvas object to exclude the 
last cell, and it decreases the number of cells to paint by one. 


Private Sub RedrawMe() 
Dim i As Long 
Dim x As Long 
Dim y As Long 
Dim n As Long 


" Calc number of live cells to draw. 


n = (m_Val / (m_Max - m_Min)) * m_Cells 


Draw live cells. 


m_Bar.ForeColor = m_fColor 
y = m_yMargin + m_CellHeight - 1 
X = m_yMargin 
For i=1Ton 

m_Bar.Line (x, m_yMargin) -_ 

(x + mCellWidth, y), , BF 

x = x + m_xMargin + m_CellWidth 

Next i 


" Draw dead cells. 
If n < mCells Then 
m_Bar.ForeColor = m_bColor 
For i =n +1 To mCells 
m_Bar.Line (x, m_yMargin)-_ 
(x + mCellWidth, y), , BF 
xX = x + m_xMargin + m_Cel]lWidth 
Next i 
End If 
End Sub 


- 


LISTING 2 Drawing the Emulated Progress Bar. This private 
method is called from within the CProgressBar class 


whenever the progress bar needs to be refreshed. It first draws “live” 
cells to indicate completion progress, then draws “dead” cells using 
the background color to erase the remainder of the progress bar. 


—) 
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Because the Canvas object will likely be resized, you must 
prevent recursion in case its Picture_Resize event itself calls the 
ResizeEx method. You can do this by setting a Static variable to 
True immediately before resizing the Canvas object. Upon en- 
tering the ResizeEx method, if this Static variable is found to be 
True, it is then assumed that a recursive call has been made, and 
the method is exited without further action. After the Canvas 
object has been resized, the Refresh method is called to repaint 
it using its current Value. 

A private RedrawMe method is called from the public Re- 
fresh method, and this is where the actual drawing takes place 
(see Listing 2). Knowing the cell dimensions, you need just one 
calculation to determine the number of “live” cells—those in the 
highlight color—to be drawn based on the Value property. It’s 
then a fairly simple task of drawing each cell using VB’s Line 
method with the filled box option. 

First, the program draws each “live” cell in the foreground 
color, then it draws the remaining “dead” cells using the back- 
ground color. The extra “dead” cells need to be drawn because 
progress may not be positive in all cases. A progress bar may not 
in fact move steadily from zero to 100, but may be monitoring 
something where occasional setbacks occur. In these cases, the 
program must now redraw the previously “live” cells as “dead.” 

Using the CProgressBar class in your projects is extremely 
simple; it requires only a few more steps than are required when 
using the ProgressBar control itself. When designing the form, 
place a picture box where you want the progress bar to be. Inthe 
General section of the form, include this declaration to create a 
new instance of CProgressBar named pBar: 


Private pBar As New CProgressBar 


Then, in the Form_Load event, pass areference to the picture 
box as the Canvas property of the CProgressBar instance: 


Set pBar.Canvas = Picturel 


From this point on, you can call CProgressBar’s methods and 
set its properties at will. For example, to run it through its paces, 
use a loop such as this: 


For i = 0 To 100 Step 4 
pBar.Value = I 
“ Win32 API function to delay 
“ 100 milliseconds 
Sleep 100 

Next I 

pBar.Value = 0 


If your form is resized, and you want to resize the progress 
bar to fit the new space, first resize the picture box then call 
the ResizeEx method for an integral number of cells (if exact 
fit is more important than the distraction of a partial last cell, 
CProgressBar also contains a Resize method that simply 
recalculates cell dimensions, but doesn’t adjust the Canvas 
object’s size). You can accomplish this most easily by placing 
the call to Resize(Ex) in the Picture_Resize event. Likewise, a 
call to the Refresh method would be prudent within the 
Picture_Paint event. x! 
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“As a programmer, | especially 

appreciate how easy it is to use 

ImageMan.” 

“TL have all of the available 
image processing pack- 
ages and without ques- 
tion I like yours the 
best.” 


Michael Taukus 
Data Based Advisor 


“Data Techniques is willing 

to go the extra mile to main- 

tain customer satisfaction.” 
Daniel Mendyke 


Dr. Oscar Linares 


*Of all the libraries we bought for 
inclusion in our product, yours is the 
only company we would ever purchase 
code from in the future” 


“I haye found Data Techniques 
to be very receptive to my 
needs as a customer, and they 
have been appreciative of the 
stions for enhancements 
and new features.” 
Kerry Lancaster 


“We have been impressed with the 
architecture and hope to use this strat- 
egy in Our own application 
Tim McCarthy 
Pilot Software 


“T like the interface to your 
product. It’s one of the simplest 
est API’s I have used for 


“The best thing about the IwageMan 
control is speed.” 


Steve Okonski 
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ImageMan:—Trusted By More Of The 
Companies You Trust 


ImageMan is used in more off-the-shelf applications than any other imaging 
library available, including applications like: 


LotusApproach My Advanced Label Designer 
CorelDraw My Advanced Mailing List 
DataEase Express Avery LabelPro 

Zylab ZyIndex Gupta SOLWindows 
Milestones, Etc. (Kidasa) More... 


These companies didn’t choose /mageMan because of slick advertisements or 
meaningless guarantees. They chose JmageMan because it meets their real- 
world image processing needs. They chose /mageMan because it’s the fastest, 
easiest to use, and most comprehensive solution they could find. And they 
chose ImageMan because ImageMan is clearly a technically superior product. 
Take the time to compare JmageMan’s demo with those of our competitors, 
compare the APIs, and you'll come to the same conclusion that some of the 
best programmers in the industry have already reached: ImageMan is the 
only choice for creating truly world-class products. That’s why JageMan is 
a Visual Basic Programmer's Journal Readers’ Choice award recipient, and 
that’s why JmageMan users are so devoted. 


ImageMan has always been offered with an unconditional 90-day money-back 
guarantee (yes, even the 32-bit versions). We can offer this extraordinary 
guarantee because of our extremely high level of confidence in our product. 
Can our competitors say the same? 


ImageMan is available royalty-free in DLL or VBX/OCX format for Windows 
3.1, Win32s, and Windows NT. Source code available. 


— a 300 Pensacola Road 

: Burnsville, NC 28714 

(704) 682-4111 

Fax: (704) 682-0025 

BBS: (704) 682-4356 
Web: www.data-tech.com 


Big 


DATA TECHNIQUES. INC. 


Users type ordinary English requests. 


[= 


English Wizard Query Builder 


What customers didn't have any orders last month? [| 


English Wizard translates the 
English and returns the SQL 
to your application 


English Wizard's Interpretation 


SELECT ‘Customers*..Company Name”, “Customers~.‘Contact Name 
FROM “Customers~ 

| WHERE not Exists([SELECT “Ship Name’ FROM ‘Orders’ WHERE 
i {fn Month{‘Order Date’)}=12 and {fn Year{"Order Date*)}=1995 and 
~Customers’."Customer ID*="Orders*.‘Customer ID*) 


Let English Wizard.. 
Do it for You! 


Developing applications that dynamically generate SQL in response 
to user input is a difficult problem. Your application design either 
restricts the user to choosing from specific data values, or forces 
the use of a general purpose ad hoc query dialog. The first option 
limits the user too much and the second is much too complex to 
use. Let English Wizard do it for you! Let the user describe the 
data they want in ordinary English and let English Wizard generate 
the SQL for you, dynamically. 


English Wizard allows your users to express their requests using 
ordinary English and then translates the English into SQL for you in 
either the ODBC or the native SQL dialect for Microsoft Access, 
SQL Server, Oracle or Informix. If the user’s wording is 
ambiguous, English Wizard will ask the user for clarification. 


Because English Wizard understands the seemingly simple English 
phrases that require complex SQL, English Wizard will dramatically 
extend the capabilities of your application. For example, if your 
application provides extensive analysis of customers selected by 


& Order your copy of 
Qs English Wizard 
today! 


(Visa, MC, AMEX Accepted) 


Ky 
x ae. ¢ For further information or to place an order for English Wizard, 
call 800-425-8200 or fax 610-325-7506 
Internet: http//world.std.com/~engwiz 


the user, English Wizard would allow the user to select customers 
based on questions such as: 
yx “customers that bought the most seafood last year” or 
xx “customers who bought both seafood and dairy products” or 
yx “customers who shipped by Federal Express exclusively”. 


English Wizard will automatically generate the complex sub-selects 
required by these questions. 


Join thousands of companies like PeopleSoft, Inc., Health Payment 
Review and NetSoft who have embedded English Wizard into their 
applications. 


English Wizard is an open solution that works with nearly all 
client/server application development languages and reporting 
tools: 


Microsoft Access PowerBuilder C/C++ 

Visual Basic NewEra DELPHI 

Forest & Trees Intersolv Q+E R&R Report Writer 

InfoMaker ReportSmith Microsoft Excel & Query 
..and more 


The English Wizard 
Software Developer’s Kit is 
only $149*. To simplify use 
with several programming 
languages, the English 
Wizard SDK includes a VBX 
control, an OCX control, a 
PowerBuilder user object, a 
NewEra object, a Delphi 
control and a C=callable 
API. Special Deployment 


Pricing available! 
*Plus shipping, handling and 
applicable sales tax 


Linguistic Technology Corporation 
179 Great Road, Patriot Square, #220 Acton, MA 01720 
©1996 Linguistic Technology Corporation. All rights reserved. English Wizard is a trademark of Linguistic Technology Corporation. All trademarks and registered trademarks are property of their respective owners. 


TAG196-VB 


Tray Cool! 


by Corl Franklin 


HAVE IT YOUR WAY 

Some apps, such as PowerToys (FSR Monitor and 
QuickCD) and a mail notification program, run on the 
tray of Windows 95 in the area where the volume indicator and 
time are located. How can | create a program with the icon 
loaded into this area? Is it an API call? 

—Matthew A. Griffith, received by CompuServe 


Steve Cramp of Dolphin Systems (www.dol- 
phinsys.com) found the answer to this question on 
the Microsoft Developer Network CD. The Windows 95 
Shell library contains a function to quickly and easily add, 
modify, or delete an icon from the tray. You also can give a tray 
icon a tool tips-style message to display when the mouse moves 
over the icon. The code involves the use of a user-defined type 
called NOTIFYICONDATA and the function Shell_NotifylconA in 
SHELL32.DLL (see Listing 1). 

You will probably want to download this code from either the 
VBPJ Forum on CompuServe (GO VBPJFO, Magazine Library, 
QA0396.ZIP) or Carl & Gary’s VB Home Page (http:// 
www.apexsc.com/vb/ftp/misc/q&a0396.zip) because this sample 
app has 16 icons that, when animated, look like a spinning globe. 
The app cycles through each icon, updating both the form icon 
and the tray. When the app unloads the form, it removes the icon 
from the tray. 


CANCELING THE UNLOAD EVENT 

How do] exit a Form_Unload procedure? I’m trying to 
make my app look as professional as possible. [havea 
routine set up that asks the user if he wants to save his work 
before exiting. I query the user “Save file before exiting?” with 
three options: Yes, No, or Cancel. If the user decides instead to 
exit by double-clicking on the top-left form control box, Cancel 
will not allow me to exit the unload procedure via an Exit Sub 
statement. Is there an easy solution to this? 


Carl Franklin is a software developer, and the co-owner of Carl & 
Gary’s Visual Basic Home Page (http://www.apexsc.com/vb). 
Contact Carl by e-mail at carlf@apexsc.com or through Visual 
Basic Programmer’s Journal. CompuServe users, address your 
mail to internet:carlf@apexsc.com. 


This is your forum for addressing the intricacies of the Visual 
Basic language. Send your questions, clever tips, and tech- 
niques. Visual Basic Programmer’s Journal will pay $25 for any 
submission, tip, or question we print. If your submission in- 
cludes code, please send a disk along with your hard copy. Mail 
submissions to Q&A Columnists, c/o Fawcette Technical Publi- 
cations, 209 Hamilton Avenue, Palo Alto, CA, USA, 94301-2500. 
pee eee: 74774,305. 


Second question: is there a way to put text into a MaskedEdit 
Text control? There is no Text or Caption property for this 
control, so if I have a default value for this entry box I have to 
display it outside in a label. 

—Zsolt Halmos, Los Gatos, California 


ICON.BAS 
"-- Used by Shell_NotifyIconA 
Type NOTIFYICONDATA 
cbSize As Long 
"-- Handle of the window that receives 
S notification messages 
hWnd As Long 
"-- App-defined identifier of the 
Y taskbar icon 
uID As Long 
'-- Flags 
uFlags As Long 
'-- App-defined message identifier 
uCallbackMessage As Long 
"-- Handle to an icon 
hIcon As Long 
"-- Tool text display message 
szTip As String * 64 
End Type 
Global Const NIM_ADD = 0 
Global Const NIM_MODIFY = 1 
Global Const NIM_DELETE = 2 
Global Const NIF_MESSAGE = 1 
Global Const NIF_ICON = 2 
Global Const NIF_TIP = 4 
Declare Function Shell_NotifyIconA Lib _ 
"shel1l32" (ByVal dwMessage As Long, _ 
IpData As NOTIFYICONDATA) As Integer 
ICON. FRM 
Option Explicit 
Dim nPos As Integer 
Private Sub Form_Load() 
Dim nd As NOTIFYICONDATA 
Dim nRet As Integer 
"-- Fill the nd structure. 
"-- Size of the structure 


CONTINUED ON PAGE 138. 


J 


Drop Icons in the Tray. The 32-bit Shell_NotifylconA 

routine lets you add, change, or delete an icon from the 
Windows 95 Toolbar Tray. To set up, create a form with a Timer 
control. Add one picture control (Picture2) and 16 other picture 
controls as an array (Picture1(0) through Picture1(15)). For an 
icon that is not animated, remove the Timerl_Timer procedure 
and the picture controls. 
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VB Comms Suite 
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SS Giifier ToolPak 
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™ 


Crescent Internet ToolP. 
Your window to the world of the Inter- 
net for VB4. Build Internet-enabled 
applications without low-level coding 
or in-depth knowledge of Internet pro- 
tocols. There’s a mail wizard that walks 
you through your Internet application, 
building the groundwork for your mail 
project. Controls include Internet Mail 
(SMTP and POP), USENET News- 
groups, Web/http, FTP, & client/serv- 
er, and they all conform to applicable 
RFC standards. 


PDQComm*® 


Now you can develop serial communica- 
tions-based applications without low- 
level programming. PDQComm features 
a custom communication control and a 
complete library of subroutines and 
functions. Communicate with multiple 
ports, perform background file transfers, 


and exploit built-in terminal emulations. 


This may be the only serial communica- 
tions library you will ever need. 


NetPak® Professional 


Develop networked applications in 
record time. Gain access to network ser- 
vices and say good-bye to low-level cod- 
ing. NetPak Professional contains five 
custom controls and over 200 functions 
for Novel® NetWare® and Microsoft® 
Windows for Workgroups®. Boost pro- 
ductivity and enhance your application 
functionality at the same time. 


ERESCENT 


————— Division of Progress Software 


14 Oak Park Bedford, MA 01730 USA 
617.280.3000 


VBPJO396A 


You can reach Crescent at: Web site http://www.progress.com/crescent 


E-mail crescent@progress.com. Fax 617.280.4025 Phone 800.352.2742 


The QueryUnload event provides an opportunity to 
ask the user for information, such as when closing files 
and saving data. You can set the Cancel variable to 
True to avoid the form being unloaded. QueryUnload occurs 
before the Unload event, so the code in Unload never even 
executes. The UnloadMode parameter tells you what action is 
attempting to unload your application, such as the system 
menu’s close command or a normal exit. 
Here’s how to do this: 


Sub Form_QueryUnload (UnloadMode As Integer, _ 
Cancel As Integer) 


Select Case UnloadMode 


Case vbFormControlMenu "0 
'-- The user has chosen the Close 
y command from the Control-menu box 
‘ on the form. 


Case vbFormCode ae | 
"-- The Unload method has been invoked 
. from code. 

Case vbAppWindows * 2 


CONTINUED FROM PAGE 136. 


nd.cbSize = Len(nd) 
'-- The form's hWnd 
nd.hWnd = Forml.hWnd 
"-- Specify Null for the ID 
nd.uID = vbNul] 
"-- No callback procedure 
nd.uCallbackMessage = vbNull 
"-- Specify the Icon 
nd.hIcon = Forml.Icon 
"-- Set the flags to tell Shell that we are 
v specifying the CallbackMessage, Icon, 
and Tip 
nd.uFlags = NIF_MESSAGE Or NIF_ICON Or NIF_TIP 
'-- Add the Icon 
nRet = Shell_NotifyIconA(NIM_ADD, nd) 
"-- Adjust the size of the form 
Width = 3100 
Height = 1500 
End Sub 


Private Sub Form_Unload(Cancel As Integer) 
Dim nd As NOTIFYICONDATA 
Dim nRet As Integer 
"-- Size of the structure 
nd.cbSize = Len(nd) 
'-- The form's hWnd 
nd.hWnd = Forml.hWnd 
"-- Specify Null for the ID 
nd.uID = vbNull 
'-- No callback procedure 
nd.uCallbackMessage = vbNull 
"-- Set the flags to tell Shell that we are 
specifying the CallbackMessage, Icon, 
‘ and Tip 
nd.uFlags = NIF_MESSAGE Or NIF_ICON Or _ 
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-- The current Windows-environment 
session is ending. 
Cancel = True 


Case vbAppTaskManager Es 
'-- The Microsoft Windows Task Manager 
is closing the application. 
Cancel = True 


Case vbFormMDI Form ia 
"-- An MDI child form is closing 
because the MDI form is closing. 
Cancel = True 
End Select 
End Sub 


The Masked Edit control has a Text property, but it isn’t 
visible in the property window. It works like the standard text 
control works, except that according to the manual, when you 
set it programmatically, the string “must match the characters 
in the input mask exactly, including literal characters and 
underscores.” In other words, if you use the default social 
security number mask, “###-##-####,” you would have to set 
the Text to something like “123-12-3213” or some other number 
that uses the mask format. J 


NIF_TIP 
-- Delete the Icon 

nRet = Shell_NotifyIconA(NIM_DELETE, nd) 
End Sub 


Private Sub Timerl_Timer() 

Dim nd As NOTIFYICONDATA 

Dim nRet As Integer 

"-- Cycle the picture and icon 

Forml.Icon = Picturel(nPos).picture 

Picture2.picture = Picturel(nPos).picture 

nPos ="nPRos 1 

If nPos = 16 Then 
nPos = 0 

Endakf. 

'-- Size of the structure 

nd.cbSize = Len(nd) 

"-- The form's hWnd 

nd.hWnd = Forml.hWnd 

"-- Specify Null for the ID 

nd.uID = vbNul1 

"-- No callback procedure 

nd.uCallbackMessage = vbNull 

'-- Specify the Icon 

nd.hIcon = Forml.Icon 

'-- Specify the Tip 

nd.szTip = "Buzz around the World, dude.” _ 
& Chr$(0) 

"-- Set the flags to tell Shell that we are 

specifying the CallbackMessage, Icon, 

4 and Tip 

nd.uFlags = NIF_MESSAGE Or NIF_ICON Or _ 
NIF_TIP 

"-- Update the Icon 

nRet = Shell_NotifyIconA(NIM_MODIFY, nd) 

End Sub 


HardCore Visual Basic 
Bruce McKinney 

ISBN 1-55615-667-7, $39.95, 
500 pages, Disk. Tap into the 
power of the Windows API 
to break through the so- 
called limits of Visual Basic. 


Visual Basic 4 Unleashed 
SAMS Development Group 
ISBN 0-672-30837-1, $45.00, 
1,200 pages. A comprehen- 
sive reference to all the 
controls used in a leading 
edge VB app. 


Building OLE Applications 
with Visual Basic 4 

Forrest Houlette 

ISBN 0-7897-0180-4, $49.99, 
800 pages, CD-ROM. Get the 
most out of OCXs and add OLE 
functionality to your VB apps. 
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Visual Basic 4.0 How-To 
Thomas, Peterson, 
Petersen, et al 
ISBN 1-57169-001-8, $39.95, 
800 pages, CD-ROM. Prac- 
tical examples and Q&A for- 
mat help you understand all 
the techniques to writing 
Windows apps. 
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The Visual Basic Enterprise 
Craig Goren, James 
Schmelzer, Jeffrey Smith 
ISBN 0-7897-0099-9, $59.99, 750 
pages, CD-ROM. Detailed un- 
derstanding of three-tier client/ 
server architecture and why its 
the architecture of the future. 
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Building Windows 95 
Applications with Visual Basic 
Clayton Walnum 

ISBN 0-7897-0209-6, $39.99, 

448 pages, CD-ROM. Build 
powerful apps that demon- 
strate all the new features in 
Windows 95. 
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CONTINUED FROM PAGE 144. 

Pornography, for that matter—vir- 
tual sex and violence, in a year or two, 
as the technology develops. Data. 

See that woman, there? She’s pulling 
up the latest sales figures from New 
York, though it’s still three in the morn- 
ing there. That guy in the booth next to 
her? He’s filing a press release, that in 
four seconds will be printed out in 
Singapore. 

Gutenberg (grasping at the familiar concept): 
Printed, ah. And on what sort of press? 
Our press, before that rascal Fust took 
everything, had been an old wine press. 
Gates: No more presses, Mr. G. Just the 
touch of light. No more lead molds and 
messy old ink balls leaking lamp black 
and linseed oil. It’s all bytes and pixels 
and lasers now—no human muscle 
needed. 

Gutenberg (squinting down): And yet these 
glowing faces—what do you call them? 
Gates: Computer screens. 

Gutenberg: And yet these screens con- 
tain what seem to be letters, though 
very unbeautifully formed. Crude and 
hateful to the eyes though they are, a 
monk in his scriptorium could make 
sense of them, and set to copying them. 
How have letters survived your elec- 
tric revolution? 

Gates: Merely as a human convenience. 
The computers don’t use them; they 
talk to themselves and to each other in 
bits, the smallest possible unit of infor- 
mation. 

A bit is the presence or absence of a 
pulse of electricity in an instant of time, 
or else the presence or absence of a 
charge of static electricity in a memory 
device. 

Doesn’t sound like much, but they 
add up to quite a web of input and 
output as they move around through 
systems of built-in switches called, fun- 
nily enough, gates. It’s hard to explain, 
and you can’t see a thing without a 
microscope, but, believe me, it works. 

When these machines do math, it’s 
not at all like you and me doing math; 
they run a wild guess through a series 
of loops enough times until they close 
in on the answer, and work on a hexa- 
decimal base of 16 instead of 10, which 
derives, as you know, from our fingers 
and toes. 

In the split second before the comput- 
ers flash the answer, they translate it 
back into 10 base, for our convenience. 

Letters are like numbers—they’re an 
interface. That’s another concept for 
you, interface. It’s like, say, the Church 


in your day was an interface between 
men and God. Or the printed page be- 
came an interface between one man’s 
brain and another’s voice. The alphabet 
was an interface between spoken lan- 
guage and the human eye. 

Already, there are computers that 
can take in and put out spoken lan- 
guage. Already, a generation or two has 
come along that can’t be bothered to 
read; it absorbs all of its information 
from television and musical tapes. 

When you think about it, the printed 
page was an awful lot of work, and nota 
healthy use of your body, sitting and 
staring. 


Gutenberg: 
You speak of this 
global Internet as if it 


transcended human 
brains; but man is 
still the measure 
of all things. 


Gates: 
That can be fixed, 


eventually. 


Face it, friend, even at the height of 
the Gutenberg revolution, only atiny frac- 
tion of mankind read, and most did it for 
business purposes. It strained the eyes, 
overexcited the brain, and was antisocial. 
Gutenberg: But... those people consulting 
with their screens, are they not read- 
ing? What does the material that holds 
the letters matter, whether it be stone, 
papyrus, vellum, rag paper, paper made 
of wood pulp, or a plastic screen? 

Further, these words made of elec- 
tric impulses, do they not need a source 
of electricity nearby and, as you say, a 
computer to render them visible? 
Though I see a number of computers 
small enough to be portable— 

Gates: Laptops, we call them. 

Gutenberg: —I see none as smalland light as 
a modern book, which requires no elec- 
tricity, and which can be entered— 


Gates: Accessed. 

Gutenberg: —by simply opening its bound, 
sequentially numbered pages. How 
could information, or intellectual ad- 
venture in its many sorts, be more hand- 
ily and—since one does not need to be 
a goldsmith to desire traces of eternal 
harmony in the objects of everyday hu- 
man use—pleasingly packaged? 

Gates (holding up a small, exquisite, iri- 
descent disk, a CD-ROM): In my hand, | 
hold thousands of pages, reduced to 
magnetized digits. 

Already, the sales of paper encyclo- 
pedias, in their many ponderous vol- 
umes, are withering before the appeal 
of these shimmering disks, which, in the 
flicker of a few computer keys, will yield 
not only the desired information but 
illustrative pictures in 64-color display, 
diagrams that can be explored like three- 
dimensional models, and specimens of 
music, played aloud! 

Access and amplitude—these are the 
virtues of digitized information—the card 
catalogues of entire libraries, the bulging, 
groaning repositories of the fading, crum- 
bling fruit of your revolution have been 
reduced to computer memory, exhaus- 
tively searched in a twinkling! No more 
fumbling at dog-eared pages. You had 
your day, old fellow, your five centuries I 
should say, and now we must pack up 
your clumsy, dust-collecting, forest-wast- 
ing printed matter. 

This Fair beneath us is in truth a wake, 

just as, in the words of your great Ger- 
man philosopher Nietzsche, churches 
are in the truth the tombs and sepul- 
chres of God. 
Gutenberg (hesitantly): Perhaps the book, 
like God, is an idea some men will cling 
to. The revolution of print pursued a 
natural course. Like ariver, print flowed 
to its readers, and the cheapness of the 
means permitted it, where the channel 
was narrow, to trickle. 

This electronic flood you describe has 
no banks; it massively delivers, but what, 
to whom? There is something intrinsi- 
cally small about its content, compared 
to the genius of its workings. 

And—if I may point out a technical 
problem—its product never achieves au- 
tonomy from its means of delivery. A 
book can lie unread for a century, and all 
it needs to come tolifeis to be scanned by 
a literate brain. 

This CD-ROM of yours—what ma- 
chine will be able to read it a hundred 
years from now? Each generation of 
these machines destroys the previous; 
the very speed and momentum of your 
revolution erode its contact with the 
earth. You speak of this global Internet 
as if it transcended human brains; but 
man is still the measure of all things. 
Gates (collapsing with a hiss): That can 
be fixed, eventually. x! 
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(AND THE REST OF US) 
COULD LEARN FROM 
THE INVENTOR 

OF MASS 
COMMUNICATIONS. 


Dialogue in 
Cyberspace 


cene: The spirits of printing pioneer Johannes Gutenberg and computer 
Si kid Bill Gates hang above the Frankfurt Book Fair. Both are the size 

of barrage balloons, silvery and lightly tethered. Such morphing is no 
problem for the magical software of Mr. Gates, but the great enlargement 
poses a problem for Herr Gutenberg, since so little is known about him, and 
that mostly from lawsuits. The shadowy details make enormous dark patches 
in his inflated image. Vagueness in, vagueness out, as the saying goes. 

Beneath these two hovering spirits there sprawls the Fair, a bustling 
market of the publishing industry—books, stalls, posters, salesmen, even 
authors, quaint doomed creatures carefully shepherded about, by vivacious 
publicity facilitators wearing miniskirts and spike heels, from one ill-attended 
press conference to another. 

There is a constant hubbub, as on the deck of a sinking ship, of people 
keeping one another’s courage up. 

Gutenberg (marveling): What a circus! This commodity must be as precious as gold! 
Gates: Cheap as dirt, actually. And on the way out. It’s called print. You 
invented it. Or so history claims, faute de mieux. 
Gutenberg: Printing was one of my sidelines—I was a goldsmith, by trade. Such 
fine work I used to do! After the intricacies of a signet ring or anecklace clasp, 
the technology of movable type seemed a game. 

One engraved the punches of hardened steel—this was an old process—and 
then punched the copper matrices, and then poured the type, of lead strength- 
ened with tin and zinc; the hard part, the stroke of genius, was the adjustable 
mold, composed of two L-shaped pieces. Letters, you see, are not all of the same 
width, but it was important that the pieces of type be the same height and the 
same depth—else the inked impression would be hopelessly uneven. 

Gates (impatient with all this obsolete technology): Yeah, yeah. | remember a 
similar problem arose when I was mapping the first version of Microsoft 
Basic— 

Gutenberg (who is slightly deaf, from all those years of gold hammering): The thing 
about those first books, we wanted them to be beautiful, just like the finest 
manuscripts. The Bible and the Psalter had to have ornamental initials, in two 
sections, each inked separately and reassembled for each impression. It was 
tedious, but we thought if the books reflected God’s glory less fully than the 
manuscripts that the monks turned out, nobody would take them seriously. 

This idea of mass production, of many different books, of new books all the 
time, it came later, after Fust foreclosed and took everything from me, and 
Peter Schoeffer, that traitor, went over to him, with all that I had taught him. 
Gates: Lawsuits, don’t mention them. Microsoft must have 60 going at any one 
time. These information revolutions, they don’t come friction-free. 

Gutenberg: What is this Microsoft? The title of a romance? The angels tell me 
that, once people lost interest in religion, they began to read fables called 
romances, and all sorts of godless mischief ensued, for which my invention 
was to blame. 
Gates: Microsoft is bigger than a book, by a factor of billions. It makes 
programs, which are ways to make a book, among other things. A program is 
the software, and the hardware is those little boxes you see down there, with 
the shining faces. 
Gutenberg: Ah, I thought perhaps those were a new species of human being— 
heads without bodies. I see they are often consulted, like sages, and the 
alphabets attached to them are often caressed. 
Gates: They’re better than heads, actually. The circuits are more logical than 
a brain’s circuits—no sex, no religion, no funky old anger and fear. No ego. 
Pure computing and memory. And communication—wow, do they communi- 
cate! And we’re just at the beginning! If this were the print revolution, we’re 
not even at the year 1500. The presses haven’t begun to roll, man! 
Gutenberg (peering down politely): And what are they communicating? 
Gates (momentarily at a loss): Why, you know—stuff. Information. Anything 
you communicate any other way, but faster. Bank statements. Airline reser- 
vations. Love letters, if you’re into that, and the significant other is also on 
the Internet. 

CONTINUED ON PAGE 143. 
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PUT AN END TO 
CLASS STRUGGLES. 


Introducing ClassAssist- the Revolutionary Class Manager for Visual Basic 4.0 


ClassAssist 


ClassAssist is a revolutionary new prod- 
uct from Sheridan Software that will 

. change the way you use classes in Visual 
Basic’ 4.0. It adds features and capabil- 
ities that make Visual Basic 4.0 classes 
more oop-like, more powerful and easier 
to use. With ClassAssist, creating reu- 
sable classes that inherit functionality 
from other classes is as simple as point- 
ing and clicking. And overriding inher- 
ited properties or methods is just as 
easy! Whether developing alone or as 
part of a team, ClassAssist is the ideal 
tool for both the novice and experienced 
Visual Basic Developer. 


s WinAPI OBLETS- 


With WinAPI Oblets you never have 
to declare API functions or constants. 


Simply dimension the Oblet that con- 
tains the API functions you want to use, 
and you're ready to access methods and 
properties immediately! ClassAssist lets 
you take advantage of Sheridan’s advan- 
ced Oblet technology today! 


je ‘Alarm’ 
method of your clas: 
‘when the timer expires 


MyTimer. Enabled = True ‘starts the timer 


The heart of the ClassAssist IDE is the Class Explorer. It shows the relationships 
between all classes in the current library in an easy to read outline view 
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Right-click the mouse in the Explorer to derive a new class, edit properties and 
methods of an existing class or checkin/checkout classes in a shared library 


ClassAssist lets you organize your class hierarchies into multiple libraries 
and lets you decide whether a library is private or shared with the team 


The ability to create a new class that inherits functionality from an 
existing class makes you more productive and encourages code reuse 


Use ClassAssist to create libraries of reusable classes that can be 
shared by all developers in your group. Create visual classes like 
specialized listboxes, or make non- visual classes that encapsulate 
important business rules 


Visual Classes are derived from one of six supplied base classes. Listbox, Combobox, 
Command Button, State Button, Textbox and Canvas. By creating a new class that is 
derived from one of these six classes, you can create specialized custom controls to 
use in your project 


For those special situations where you need to process specific Windows’ messages, 
ClassAssist lets you define a class message map which causes messages of the 
chosen types to be routed to a method in your class for processing 
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ClassAssist walks you through the process of defining methods for 
your classes. You can even define overloaded methods - ie., 
methods with the same name that take different sets of parameters 


Sheridan. 


ClassAssist 


Reusable Components and Productivity Tools 
for the Visual Developer 


Sheridan Software Systems, Inc. 

35 Pinelawn Road, Suite 206E, Melville, NY 11747 
Manufacturer’s List Price: Voice: (516) 753-0985 ¢ Fax: (516) 753-3661 ¢ BBS: (516) 753-5452 
S$ 249.00 CIS: GO SHERIDAN ¢ http://www. shersoft.com 


©1995 Sheridan Software Systems, Inc. All rights reserved. ClassAssist, Oblets and the Sheridan logo are trademarks of Sheridan Software Systems, Inc. Visual Basic and Windows are registered trademarks of Microsoft Corporation. 


with More than 50 Powerful 


32-Bit OLE controls, 


WicroHelp 


WETools 


Cool Tools for Visual Program” 


ed 


we just couldn’t 
contain it any 
longer! 


y 


Introducing OLFTools’’ new from MicroHelp. OLETools is the © Multimedia controls add images, moving images and sound. 

successor to our best- selling custom control add-on, VBTools, ¢ Network control accesses Windows®-supported networking 

and it’s packed with even more! functionality. 

© Over 100 16- and 32-bit OLE controls. Plus dozens more ... backed with MicroHelp’s full technical 

© Design state-of-the-art interfaces with controls like Calendar support. So get a hold of real visual programming power. 
and Tab. Call today! 


© Tree control for displaying hierarchical type data such as 


directories and files. 
cool tools for Visual programming. 
ie ce) ie ip go guild something. 


OLETools” isc trademark of MicroHelp Inc. mG Em 
Windows® is 0 registered trademark of 


Wo Gases Comporeal predic pi lElee 1-800-922-3383 


